Skip to main content
API docs by Redocly

Customer API (1.0.0)

Download OpenAPI specification:Download

Administrator

Admin users API

Business

Get Red Tractor Certificates

Retrieve all valid or grace statused Red Tractor certifications for this business

Authorizations:
jwt
query Parameters
country
required
string = 3 characters
Default: "GBR"

ISO3 country code

postcode
string

Postcode of location

holdingNumber
string

Holding number for scheme

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Business

Retrieve business for a business unit

path Parameters
id
required
string

Business Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "businessUnitId": "string",
  • "organisationId": "string",
  • "location": {
    },
  • "businessName": "string",
  • "name": "string",
  • "phone": {
    },
  • "email": "string",
  • "tags": [
    ],
  • "locationTag": "string",
  • "managementTag": "string",
  • "assuranceScheme": "RT",
  • "holdingNumber": "string",
  • "sqc": {
    },
  • "assurance": {
    }
}

Get Businesses by business unit IDs

Retrieve business for a business unit

query Parameters
ids
required
string

Comma separated list of ids

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Business Units

Create Business Unit

Create a new business unit within an organisation

Authorizations:
jwt
Request Body schema: application/json
organisationId
required
string

Organisation id to which the business units belong

name
required
string

The name of the business unit

type
required
string
Enum: "farm" "stores" "region"

The type of business unit being created

object

Responses

Request samples

Content type
application/json
{
  • "organisationId": "string",
  • "name": "string",
  • "type": "farm",
  • "business": {
    }
}

Response samples

Content type
application/json
{
  • "ordinal": 0,
  • "id": "string",
  • "name": "string",
  • "type": "farm",
  • "tags": [
    ],
  • "business": {
    },
  • "storeCount": 0,
  • "fieldCount": 0
}

Get Business Units Summary

Retrieve business units summary for an organisation all of them without filtering by users business units

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

Content type
application/json
{
  • "organisationId": "string",
  • "organisationName": "string",
  • "tagGroups": [
    ],
  • "businessUnits": [
    ]
}

Get BusinessUnit

Retrieve business units for an organisation filtered by user

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationRegionISO": "string",
  • "tagGroups": [
    ],
  • "businessUnits": [
    ]
}

Update Business Unit

Updates an Organisations business unit properties

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
name
string or null

The name of the business unit

object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "business": {
    }
}

Response samples

Content type
application/json
{
  • "ordinal": 0,
  • "id": "string",
  • "name": "string",
  • "type": "farm",
  • "tags": [
    ],
  • "business": {
    },
  • "storeCount": 0,
  • "fieldCount": 0
}

Delete Business Unit

Delete Business Unit

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

Import a batch of business units

CSV Import endpoint to create a set of business units

Authorizations:
jwt
Request Body schema: multipart/form-data
organisationId
string or null
organisationName
string or null
file
required
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 0,
  • "validation": 0,
  • "errors": 0,
  • "results": [
    ]
}

Business Connections

Business connections are organisations with whom customers have a business relationship. This entity stores contacts, and other meta data associated with the relationship

Create Business Connection

Creates a new business connection for a customer. This endpoint requires that a user has a valid access token and will uses their own organisation id to attach the busines connection. When a connection object is passed to the endpoint, it will create any contacts sent with payload as users in the organisation. These users are not standard users, they will have a password generated for them, but they will not recieve an invitation email to set up their account in the platform.

Authorizations:
jwt
Request Body schema: application/json
id
string or null

The ID of any existing organisation that is to be connected to the calling organisation

companyNumber
string or null

Legal number associated with an incorporated business

countryISO
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

name
string

Name of the business

relationship
string or null
Enum: "trading" "storage" "carrier" "organiser"

Type of relationship between the 2 businesses

required
Array of objects

The contact records that are to be stored agains the new organisation or an existing organisation

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "relationship": "trading",
  • "contacts": [
    ]
}

Response samples

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

Get Business Connections

Retrieves the business connection record for the organisation The response includes all contacts that belong to the organisation connected

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

tags
string

Filter by tags

Responses

Response samples

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

Check Business Connection Exists

Takes the create business connection payload and checks to see if any of the users or email domain exists in the system, if so the matching organisation is returned. Also checks matching organisation names

Authorizations:
jwt
Request Body schema: application/json
id
string or null

The ID of any existing organisation that is to be connected to the calling organisation

companyNumber
string or null

Legal number associated with an incorporated business

countryISO
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

name
string

Name of the business

relationship
string or null
Enum: "trading" "storage" "carrier" "organiser"

Type of relationship between the 2 businesses

required
Array of objects

The contact records that are to be stored agains the new organisation or an existing organisation

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "relationship": "trading",
  • "contacts": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "blockNewConnection": true,
  • "organisations": [
    ]
}

Check Business Connection Exists To Your Organisation

Checks to see the target organisation has a business connection to your organisation

Authorizations:
jwt
Request Body schema: application/json
organisationId
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "isInNetwork": true
}

Sync Business Connection

Ensure all users in business connections exist as users

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

Delete Business Connection

Removes an organisation from the connected businesses of the calling organisation. Will return the business connection record with the remaining connected organisations and their contacts

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

Adds a relationship to a business connection

Adds a relationship to a business connection and executes any relevant actions required by the relationship

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

relationship
required
string

Relationship Type

Responses

Response samples

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

Delete contact

Removes a contact from a connected organisation

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

userId
required
string

User Id

Responses

Response samples

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

Connect Business Connection Contact

Connects a user from the authenticated users business connections contact list with your organisation, once connected organisations can permission this external user to access resources within their account

Authorizations:
jwt
path Parameters
id
required
string

Connected organisation Id

userId
required
string

Contact user ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Disconnect Business Connection Contact

Removes an external user from authenticated users organisation and prevents access to their account

Authorizations:
jwt
path Parameters
id
required
string

Connected organisation Id

userId
required
string

Contact user ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Cognito

Manage user syncing from Cognito to Database and vice versa.

Create an admin user in Cognito

Create an admin user in Cognito

Authorizations:
jwt
Request Body schema: application/json
email
required
string
password
required
string <cognito-password>

Standard cognito password

givenName
required
string
familyName
required
string
readonly
required
boolean
Default: "false"

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "givenName": "string",
  • "familyName": "string",
  • "readonly": "false"
}

Response samples

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

Create users in Cognito

Creates users in Cognito from the user account in RavenDB. All RavenDB users will be recreated

Authorizations:
jwt

Responses

Response samples

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

Swap a user from one pool to another on login

Swap a user from one pool to another on login

Request Body schema: application/json
username
required
string
password
string <cognito-password>

Standard cognito password

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": "not-found",
  • "authenticated": true,
  • "id": "string"
}

Sync all users to Cognito and update Raven if roles have changed

Sync all users to Cognito and update Raven if roles have changed

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

removeUserAttributes

Authorizations:
jwt

Responses

Response samples

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

cleanCognitoAccounts

Authorizations:
jwt

Responses

Response samples

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

Create User in Cognito

Create a user in Cognito from a user account in RavenDB

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

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

Sync to Cognito

Sync user record from a RavenDB user to Cognito

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

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

Sync from Cognito

Sync information from Cognito to RavenDB for a single user

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

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

Organisations

This API manages the organisation information of customers of Platform

Create organisation

Create a new customers organisation

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

Name of the business

countryISO
required
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

required
object or null
Array of objects or null
organisers
Array of strings
required
object or null
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "location": {
    },
  • "company": {
    },
  • "name": "string",
  • "countryISO": "GB",
  • "ownerContact": {
    },
  • "contacts": [
    ],
  • "organisers": [
    ],
  • "billing": {
    },
  • "modules": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Get Organisations

Get Organisations

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

tags
string

Filter by tags

status
string

Filter by status

count
boolean

If true just return a count

query
string

Free text search field for querying

modules
string

Modules

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get organisations by id

Get organisations records by id

Authorizations:
jwt
query Parameters
ids
required
string

Comma separated list of ids

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get organisation of the logged in user

Get organisation of the logged in user

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "location": {
    },
  • "countryISO": "GB",
  • "status": "active",
  • "companyId": "string",
  • "companyHoldingNumber": "string",
  • "bio": "string",
  • "logo": {
    },
  • "ownerContact": {
    },
  • "billing": {
    },
  • "settlementContacts": [
    ],
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "sqc": {
    },
  • "assuranceScheme": "RT",
  • "advancePay": {
    }
}

Get carrier organisations

Get carrier organisations

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Organisation

Get Organisation

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Update Organisation

Updates an Organisations properties

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
object or null
object
name
string or null

Name of the business

countryISO
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

object or null
Array of objects or null
organisers
Array of strings
object or null
Array of objects
bio
string or null
Deprecated
companyHoldingNumber
string or null
Deprecated
website
string or null
Deprecated
companyNumber
string or null

Legal number associated with an incorporated business

companySalesTaxId
string or null
Deprecated
inventoryType
Array of strings or null
Deprecated
Array of objects or null
object or null
status
string or null
statusMessage
string or null
vetted
boolean
isMerchant
boolean

Responses

Request samples

Content type
application/json
{
  • "location": {
    },
  • "company": {
    },
  • "name": "string",
  • "countryISO": "GB",
  • "ownerContact": {
    },
  • "contacts": [
    ],
  • "organisers": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "bio": "string",
  • "companyHoldingNumber": "string",
  • "website": "string",
  • "companyNumber": "string",
  • "companySalesTaxId": "string",
  • "inventoryType": [
    ],
  • "settlementContacts": [
    ],
  • "logo": {
    },
  • "status": "string",
  • "statusMessage": "string",
  • "vetted": true,
  • "isMerchant": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Update Organisation Advance Pay Details

Updates an Organisations advance pay details

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
accountName
required
string
sortCode
required
string^\d{2}-\d{2}-\d{2}$
accountNumber
required
string^\d{8,18}$
status
boolean or null

Responses

Request samples

Content type
application/json
{
  • "accountName": "string",
  • "sortCode": "string",
  • "accountNumber": "string",
  • "status": true
}

Response samples

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

Import a batch of organisations

CSV Import endpoint to create a set of organisations

Authorizations:
jwt
Request Body schema: multipart/form-data
organisationId
string or null
organisationName
string or null
file
required
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 0,
  • "validation": 0,
  • "errors": 0,
  • "results": [
    ]
}

Import a batch of preferences

Authorizations:
jwt
Request Body schema: multipart/form-data
organisationId
string or null
organisationName
string or null
file
required
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 0,
  • "validation": 0,
  • "errors": 0,
  • "results": [
    ]
}

set preferences

Authorizations:
jwt
Request Body schema: multipart/form-data
organisationId
string or null
organisationName
string or null
file
required
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 0,
  • "validation": 0,
  • "errors": 0,
  • "results": [
    ]
}

Import FinMid account status

Authorizations:
jwt
Request Body schema: multipart/form-data
organisationId
string or null
organisationName
string or null
file
required
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 0,
  • "validation": 0,
  • "errors": 0,
  • "results": [
    ]
}

Roles

Get Roles

Returns a list of roles grouped by functional area

Authorizations:
jwt

Responses

Response samples

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

Users

Change Owner

Changes the owner of the organisation

Authorizations:
jwt
Request Body schema: application/json
newOwnerUserId
required
string

The user id to be the new owner

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Get Users

Get Users

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

query
string

Free text search field for querying

status
string

Filter by status

count
boolean

If true just return a count

organisationId
string

Organisation Id

organisationIds
string

Permissioned Organisation Id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create user

Create a new customer user. This endpoint can only be used by team owners creating users for their organisation

Authorizations:
jwt
Request Body schema: application/json
givenName
required
string
familyName
required
string
countryISO
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

organisationId
string
email
required
string
phone
required
string or null <phone-number>

Phone number

pushToken
string or null
roles
Array of strings or null

The role this user has

businessUnits
Array of strings or null

The user business units, list of ids

Responses

Request samples

Content type
application/json
{
  • "givenName": "string",
  • "familyName": "string",
  • "countryISO": "GB",
  • "organisationId": "string",
  • "email": "string",
  • "phone": "string",
  • "pushToken": "string",
  • "roles": [
    ],
  • "businessUnits": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Delete User

Delete User

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

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

Get User

Get User

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Patch User

Patch User

Authorizations:
jwt
path Parameters
id
required
string

User Id

Request Body schema: application/json
givenName
string
familyName
string
countryISO
string = 2 characters
Default: "GB"
Enum: "GB" "US" "ZA" "FR"

Country where the business is based, two letter code

organisationId
string
email
string
phone
string or null <phone-number>

Phone number

pushToken
string or null
roles
Array of strings or null

The role this user has

businessUnits
Array of strings or null

The user business units, list of ids

phoneLandline
string or null <phone-number>

Phone number

object or null
termsAgreed
boolean or null
marketingEmails
boolean or null
whatsAppNotifications
boolean or null
smsNotifications
boolean or null
harvestNotificationDismissed
boolean or null
harvestDialogDismissed
boolean or null
listingsWelcomeRead
boolean or null

Responses

Request samples

Content type
application/json
{
  • "givenName": "string",
  • "familyName": "string",
  • "countryISO": "GB",
  • "organisationId": "string",
  • "email": "string",
  • "phone": "string",
  • "pushToken": "string",
  • "roles": [
    ],
  • "businessUnits": [
    ],
  • "phoneLandline": "string",
  • "avatar": {
    },
  • "termsAgreed": true,
  • "marketingEmails": true,
  • "whatsAppNotifications": true,
  • "smsNotifications": true,
  • "harvestNotificationDismissed": true,
  • "harvestDialogDismissed": true,
  • "listingsWelcomeRead": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Resend User password

Resend users temporary password (resend invite)

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

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

Verify Attribute Update

User update email and phone attribute confirmation, takes a username and a confirmation code and sets the users account to confirmed, allowing that user to login

Authorizations:
jwt
Request Body schema: application/json
code
required
string

Six digit code sent to user to confirm their update

Responses

Request samples

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

Response samples

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

Find users by preferences

Lookup user summaries for al lusers who match the incoming preferences excluding users in the organisationId supplied.

Authorizations:
jwt
query Parameters
preferences
string

User preferences array. comma separated

organisationId
string

Filter by organisation Id

Responses

Response samples

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

Set users buyer preferences

Overwrites any existing buyer preferences with the incoming array. These preferences are used to notify trade users about open trade listings.

Authorizations:
jwt
Request Body schema: application/json
One of
Array
commodity
required
number or null
grades
required
Array of numbers
regions
required
Array of strings
enabled
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "preferences": [
    ],
  • "notificationsEnabled": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Lookup User By Telephone

Lookup or create a user by a telephone number

Authorizations:
jwt
Request Body schema: application/json
phone
string or null <phone-number>

Phone number

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "type": "internal",
  • "familyName": "string",
  • "name": "string",
  • "countryISO": "GB",
  • "email": "string",
  • "pushToken": "string",
  • "external": false,
  • "impersonating": false,
  • "settings": {
    },
  • "tokens": {
    },
  • "groups": [
    ],
  • "roles": [
    ],
  • "profiles": [
    ],
  • "preferences": [
    ],
  • "phone": {
    },
  • "phoneLandline": {
    },
  • "avatar": {
    },
  • "organisationId": "string",
  • "organisationName": "string",
  • "authPlatformId": "string",
  • "status": "active",
  • "businessUnits": [
    ],
  • "notificationsEnabled": true
}

Mailchimp callback

Mailchimp callback endpoint for webhooks

Responses

Response samples

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

Mailchimp callback exists check

Mailchimp callback exists check endpoint for webhook. Mailchimp uses this endpoint to verify that the endpoint exists.

Responses

Response samples

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

Mailchimp callback exists check

Mailchimp callback exists check endpoint for webhook. Mailchimp uses this endpoint to verify that the endpoint exists.

Responses

Response samples

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

Customers

Delete an organisation

Delete an organisation and all related data

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

Impersonate an organisation

Returns an encrypted impersonation token valid for 1 hour for the specified organisation

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

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

Activate an organisation

Set an organisation to active and resent account welcome email to owner

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Adds a module to an organisation

Add a module to the organisation and configure security for the owner

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
id
required
string
name
string or null
required
object or null

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Remove a module from an organisation

Removed a module from the organisation and configure security for the owner

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
id
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "company": {
    },
  • "companyNumber": "string",
  • "countryISO": "GB",
  • "name": "string",
  • "ownerContact": {
    },
  • "settlementContacts": [
    ],
  • "status": "active",
  • "statusMessage": "string",
  • "businessUnits": [
    ],
  • "businessConnections": [
    ],
  • "billing": {
    },
  • "modules": [
    ],
  • "vetted": true,
  • "isMerchant": true,
  • "createdAtUTC": "string"
}

Send a request to CS to add a module

Sends a message to a slack channel to request a new module for an organisation

Authorizations:
jwt
path Parameters
id
required
string

Organisation Id

Request Body schema: application/json
id
required
string

Responses

Request samples

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

Response samples

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

createAccounts

Authorizations:
jwt

Responses

Response samples

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

applyAccounts

Authorizations:
jwt
query Parameters
type
string

Filter by type

Responses

Response samples

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

exportAccounts

query Parameters
type
string

Filter by type

Responses

Response samples

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

getAccount

path Parameters
id
required
string

id

Responses

Response samples

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

Retrieve authenticated users profile

Retrieves the logged in customers profile (user & org)

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "organisation": {
    },
  • "user": {
    },
  • "access": {
    },
  • "features": {
    },
  • "tokens": {
    }
}

Retrieve users by ids

Retrieve users by ids

Authorizations:
jwt
query Parameters
ids
required
string

Comma separated list of ids

Responses

Response samples

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

Retrieve users summary by ids

Retrieve users summary by ids

Authorizations:
jwt
query Parameters
ids
required
string

Comma separated list of ids

Responses

Response samples

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

Retrieve users by roles

Retrieve users by roles

Authorizations:
jwt
query Parameters
include
string

include these array items

exclude
string

exclude these array items

organisationId
string

Organisation Id

Responses

Response samples

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

Retrieve users by commodity regions

Retrieve users by commodity regions

Authorizations:
jwt
query Parameters
regionISOs
string

Region ISOs separated by commas

commodityId
required
number

Commodity ID

Responses

Response samples

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

Retrieve basic info for a user

Retrieve basic info for a user

Authorizations:
jwt
path Parameters
id
required
string

User Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "givenName": "string",
  • "familyName": "string",
  • "countryISO": "GB",
  • "organisationName": "string",
  • "organisationId": "string",
  • "email": "string",
  • "phone": {
    },
  • "pushToken": "string",
  • "organisation": {
    },
  • "preferences": [
    ],
  • "settings": {
    },
  • "authPlatformId": "string"
}

Authenticate a user based on an ApiToken

Authenticate a user based on an ApiToken and return their profile with the auth tokens

Request Body schema: application/json
token
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "organisation": {
    },
  • "user": {
    },
  • "access": {
    },
  • "features": {
    },
  • "tokens": {
    }
}

Generate an ApiToken for a user

Generate an ApiToken for a user

Authorizations:
jwt
Request Body schema: application/json
userId
required
string
hours
required
number
roles
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "hours": 0,
  • "roles": [
    ]
}

Response samples

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

User Request Full Account

Sends a request to the customer success team to set up a full account for the user.

Request Body schema: application/json
requestType
required
string
Enum: "account" "tradingBuyerAccount"
firstName
required
string
lastName
required
string
businessName
required
string
companyNumber
required
string or null
emailAddress
required
string
phone
required
string or null <phone-number>

Phone number

Responses

Request samples

Content type
application/json
{
  • "requestType": "account",
  • "firstName": "string",
  • "lastName": "string",
  • "businessName": "string",
  • "companyNumber": "string",
  • "emailAddress": "string",
  • "phone": "string"
}

Response samples

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

Admin

Generate an ApiToken for a user

Generate an ApiToken for a user

Authorizations:
jwt
Request Body schema: application/json
userId
required
string
hours
required
number
roles
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "hours": 0,
  • "roles": [
    ]
}

Response samples

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

Admin reset password

Admin initiated password reset request on behalf of a user

Authorizations:
jwt
Request Body schema: application/json
username
required
string

email or username

Responses

Request samples

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

Response samples

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

Admin set password

Admin initiated set password request on behalf of a user

Authorizations:
jwt
Request Body schema: application/json
username
required
string
password
required
string <cognito-password>

Standard cognito password

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

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

Global

Login

User initiated login

Request Body schema: application/json
username
required
string

Phone, email address or username

password
required
string
newPassword
string <cognito-password>

Standard cognito password

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "newPassword": "string"
}

Response samples

Content type
application/json
{
  • "tokens": {
    },
  • "challenge": {
    }
}

Change Password

User initiated change password request

Authorizations:
jwt
Request Body schema: application/json
email
string or null
oldPassword
required
string
newPassword
required
string <cognito-password>

Standard cognito password

confirmNewPassword
required
string <cognito-password>

Standard cognito password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "oldPassword": "string",
  • "newPassword": "string",
  • "confirmNewPassword": "string"
}

Response samples

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

Forgotten Password

User initiated forgotten password request

Request Body schema: application/json
username
required
string

email or username

Responses

Request samples

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

Response samples

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

Reset password

User initiated forgotten password confirmation request

Request Body schema: application/json
username
required
string
password
string <cognito-password>

Standard cognito password

passwordConfirm
string <cognito-password>

Standard cognito password

confirmationCode
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "passwordConfirm": "string",
  • "confirmationCode": "string"
}

Response samples

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

Logout user

Invalidates the users tokens

Authorizations:
jwt

Responses

Response samples

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

Refresh tokens

Refresh the Access and ID tokens

Responses

Response samples

Content type
application/json
{
  • "tokens": {
    },
  • "challenge": {
    }
}

Resend the users password

Resend users temporary password (resend invite)

path Parameters
id
required
string

User AuthPlatform Id

Responses

Response samples

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

User

Confirm Signup

User initiated signup confirmation, takes a username and a confirmation code and sets the users account to confirmed, allowing that user to login

Request Body schema: application/json
username
required
string

users authPlatformId

confirmationCode
required
string

Six digit code sent to user to confirm their account

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "confirmationCode": "string"
}

Response samples

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

Verify Magic Link

User was sent whatsapp link with code. Code from that link will be posted to this endpoint to verify their login.

Request Body schema: application/json
id
required
string

Auth Lookup Id

Responses

Request samples

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

Response samples

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

Authenticate a user based on an ApiToken

Authenticate a user based on an ApiToken and return their profile with the auth tokens

Request Body schema: application/json
token
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "organisation": {
    },
  • "user": {
    },
  • "access": {
    },
  • "features": {
    },
  • "tokens": {
    }
}

Change Marketplace password

User initiated change marketplace password request

Request Body schema: application/json
email
string or null
oldPassword
required
string
newPassword
required
string <cognito-password>

Standard cognito password

confirmNewPassword
required
string <cognito-password>

Standard cognito password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "oldPassword": "string",
  • "newPassword": "string",
  • "confirmNewPassword": "string"
}

Response samples

Content type
application/json
{
  • "tokens": {
    },
  • "challenge": {
    }
}

Feature Flags

Get Feature Flags

Returns a list of active feature flags and whether they are enabled or disabled

Authorizations:
jwt

Responses

Response samples

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

Set Feature Flags

Sets an array of feature flags to either enabled or disabled

Authorizations:
jwt

Responses

Response samples

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

Delete Feature Flag

Delete a feature flag

Authorizations:
jwt
path Parameters
id
required
string

Feature Flag Name

Responses

Response samples

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

System

Set Feature Flags

Sets an array of feature flags to either enabled or disabled

Authorizations:
jwt

Responses

Response samples

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

Misc

Misc

Authorizations:
jwt
query Parameters
type
string

Filter by type

Responses

Response samples

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

Customers System

Ping api

Ping customers api

Responses

Response samples

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

Execute event

Execute event in customers 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 customers 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"
}