Introduction

Welcome to VendNovation's Vendor API! You can use our API to build custom interfaces to your data within VendNovation's system.

To help you get started in your development, we provide a Postman collection that you can import. Download it here (right click and Save Link As). Our postman collection makes use of collection level variables which you can learn about here. The variable names have already been defined and inserted throughout the collection, you just need to enter your values.

By reading and using this documentation, you agree to these terms.

Concepts

General Documentation Information

Data Types

The api is written in C#, and as a result the data types in the documentation refer to C# data types. These map cleanly to similar types in other languages and generally do not need expanded upon. The only exception is the ? operator. This indicates a value may be null. So for example, if a data type is specified as bool? that indicates that the value may be null, and if it is not, then the type will be a bool. This also indicates that the api will accept a null in this field.

API Access Tokens

The Vendor API uses AWS api tokens to control access to the api and to manage rate limiting. If you do not have a token, email us!. To use your token please include a header like x-api-key: accessToken. This is required on all requests. We have a route to help you test that this is setup properly. See the Token Test route for more information.

If you do not have a token, perform the following:

1. Create one or more User(s) within the Organization that requires API access. a. We suggest api@organizationName.com for the login email. b. Set a strong password - the password for this user will be used in conjunction with an organization specific API key to authenticate against the API.
2. Contact api-request@vendnovation.com and provide your Organization Name and the login email(s) of those users you wish to enable API access for.
3. VendNovation will enable API access for those Users and send you your Organization specific API Key.

Usage Plan Details

All new API access keys are limited to the following restrictions:

Proper call optimization should allow you to stay within the limits. Remember that all calls support retrieving multiple data sets by ID simultaneously.

API Stages

The Vendor API has multiple deployments you can access. It is recommended you use the most current version of the API. The stages available currently are:

It is our goal to have the APIs exist in perpetuity, even when they are no longer receiving bugfixes. However, should a security-related issue be discovered that cannot be fixed in a non-breaking way, you will be given as much time as possible to migrate to a newer, secure version of the API.

Data Retrieval and Filters

{
  "organizationIds": [1],
  "siteIds": [1, 4, 6]
}

The Vendor API is not structured like a standard REST API (parent-resource/{parent-resource-id}/child-resource) and is instead built around bulk operations and achieving as much as possible in a single request while still having resource driven routes. To support this goal, api urls are flat. Even though accounts are a logical child resource of organizations, they are accessed at <base-url>/accounts. As the change in URL structure would imply, you are able to retrieve accounts from multiple parent organizations at the same time. The default behavior of the API is to send you all the data that you have access to. So if I have access to two organizations, and I call GET /machines, the api will return a result set of every single machine in both organizations at once.

As this is probably too broad for your use case, the API is filter driven. Almost every request accepts the standard request filter (found here) and supports multiple filters at the same time. In addition to the standard request filter, some route specific filters are also available and links to them will be found in the routes where applicable. Returning to our machines example, I could narrow it down a lot to only just the machines at any of the specified sites that also belong to a specific organization. To get a single (or a few specific machines) you would only specify machineIdentifiers. These principles apply to all routes in the API.

It is worth noting that not only retrieval is a bulk action. Every call in the api supports bulk actions across multiple tiers of parent resources. All bulk actions are treated as atomic sets, so if one element in your action fails, the entire set will be rolled back to it's initial state, and you will be notified of such, with as helpful an error message as can be provided.

DateTime Handling

Unless otherwise stated, all DateTimes are in UTC.

A Note on Time Zones

When working with DateTime filters, there are additional considerations regarding timezones. The DateTimes in our systems are stored in the local time as configured for the site/machine. The stored time for things like transactions report is the local time reported by the machine. As a result, to make working with DateTimes easier if you are not using the website for data tracking, you may consider configure your sites to be UTC.

StartDate and EndDate Clamping

When you provide a StartDate and/or EndDate in your request filter, the dates you provided will not necessarily be the dates used in your request. We apply a series of clamping rules to your DateTimes to restrict your maximum search range to no more than the maximum range (which varies between calls as performance allows) as well as generate either or both DateTimes if they were not both provided.

Here is a breakdown of this to help you understand how this works

If applicable, the API response will include additional headers to help you detect when we have modified date-time search parameters. - search-range-start-date - will contain the modified search start date and time, as applicable. - search-range-end-date - will contain the modified search end date and time, as applicable.

Also of note, the time portion of the DateTime is optional. If omitted, StartDate will be given a time of 00:00:00 and EndDate will be given a time of 23:59:59.

Pagination

Paging is universally supported in the API. Page parameters are specified by headers.

The response's headers will include the paging information we used while processing the request as well as the total number of pages available to be retrieved.

Standardized Request Body

{
    "requestFilter": {
      // Request filter values, if any, go here.
    },
    "routeFilter": {
      // Route filter values, if any, go here.
    }
    "body": {
        //Your data, if any, goes here.
    }
}

Requests made to the api have standardized JSON keys to ensure uniformity of interaction with the API. - The request filter is to be assigned to a key named requestFilter. - Any route specific filter is to be assigned to a key named routeFilter. - Any data models you provide to the api (eg for creates or updates) is to be assigned to a key named body.

To simplify making requests, you can put this in every request body (sans comments) and add data on an as needed basis.

Error Handling

{
  "code": "DATA_ACCESS", // programatically useful error code
  "message": "You tried to update one or more sites outside of your organization. No changes have been made.", // human friendly error message
  "pointers": [1, 4, 7], // an identifier used to find the problem records in your payload
  "pointerName": "Site.Id" // a string that tells you what field the pointers represent
}

When the api encounters an error, it will send back a list of error objects like the one seen in the sidebar. These objects should make it easy to programmatically detect and adjust for errors. Below is a table documenting these common error codes. If a route can have other errors not found in this table a similar table will be found in that route's documentation.

Multi-Route Filters

Request Filter

Most routes support a universal request filter to control the data that you receive back in the response. Not all routes support all features of the request filter, so in any given route's documentation page, you will see a table like below, indicating what request filter options are honored by that route. Specifying a request filter not honored by that route will not cause an error, but will also have no effect. Additionally, you can specify multiple ID filters if they are supported by the route, and they will all be applied.

Permissions Filter

All role, role right, and right related routes use the PermissionsFilter for further filtering. It's definition follows:

Templating Filter

All template, template group and template selection related routes use the TemplatingFilter for filtering. It's definition follows:

Authentication

API Key Test

Request Body

None

Response body on failure

{
    "message": "Forbidden"
}

Response body on success

Access token was valid

Description

This endpoint helps you test that your access tokens are set in your header correctly. This endpoint does not require you to be authenticated. If you POST to it with your access token configured correctly it will tell you that your token is valid. Otherwise it will respond with a forbidden message. This is a great place to start your api development!

Filters Honored

None

Returns

On Success

A string indicating your API key was valid.

Get Login Token

Your request body should look like

{
    "username": "me@domain.tld",
    "password": "password"
}

You will receive a JSON response like

{
    "accessToken": "9f57c00f-a92d-49e5-86fd-0052b56e0161",
    "userName": "me@domain.com",
    "issued": "9/3/2020 11:17:40 PM",
    "expires": "9/6/2020 11:17:40 PM"
}

Description

Given a valid Vendor login returns an access token authenticating you for data retrieval. Tokens are good for three days from generation. It is worth noting that all credentials for an organization are not created equal as what data you can retrieve is tied to the credentials permissions within that organization.

Filters Honored

None

Returns

On Success

An object containing your access token.

On Error

Organizations

Get Organizations

Request body

{
  // optional list of IDs for the organizations you want to retrieve
  "requestFilter": {
    "organizationIds": []
  }
}

Response body

[
  {
    "Id": 1,
    "AdministrativeOrganizationId": 3,
    "Name": "Generic Vending",
    "Address": "123 Some St. Anytown, USA 12345",
    "Contact": "John Smith",-
    "Type": "Manager"
  }
]

Description

Returns a set of organizations.

Filters Honored

• PermissionsFilter
  • organizationIds

Returns

On Success

The requested set of organizations.

Model Definitions

Organization Definition

Accounts

Get Accounts

Request body

{
    "requestFilter": {
      "organizationIds": [3],
      "accountIds": []
    }
}

Response body

[
    {
        "Id": 2,
        "Name": "John Vending",
        "VendorOrgId": 3,
        "ClientOrgId": 13,
        "IsVisible": true,
        "Contact": "Jane Smith",
        "TimeZone": null
    },
    {
        "Id": 3,
        "Name": "Smith Vending",
        "VendorOrgId": 3,
        "ClientOrgId": null,
        "IsVisible": true,
        "Contact": "Tom Smith",
        "TimeZone": null
    }
]

Description

Retrieves a list of accounts.

Filters Honored

• RequestFilter
  • organizationIds
  • accountIds
  • includeDeleted

Returns

On Success

The requested list of accounts.

Model Definitions

Account Definition

Sites

Get Sites

Request body

{
    "requestFilter": {
        "organizationIds": [3],
        "accountIds": [49,3],
        "siteIds": [205]
    }
}

Response body

[
    {
        "Id": 205,
        "AccountId": 49,
        "OrgId": 3,
        "Name": "ATS",
        "Contact": null,
        "CommissionPercentage": null,
        "IsActive": true,
        "TimeZone": "Pacific Standard Time",
        "IsEnabled": false,
        "MaxChargePrice": 5,
        "BillingAddress": "ATS\r\n6300 Merrill Creek Pkwy\r\nSuite A-100\r\nEverett, WA 98203",
        "ShippingAddress": "ATS\r\n6300 Merrill Creek Pkwy\r\nSuite A-100\r\nEverett, WA 98203",
        "MaximumMeterSalesJumpAllowed": 500,
        "CommissionTerms": "Net10",
        "ExternalAccountTerminalId": null
    }
]

Description

Get a list (or subset) of Sites belonging to an Organization.

Filters Honored

• PermissionsFilter
  • organizationIds
  • accountIds
  • siteIds
  • includeDeleted

Returns

On Success

The requested set of sites.

Create Sites

Request Body

{
    "body":
    [
        {
            "Id": 196,
            "AccountId": 11,
            "OrgId": 3,
            "Name": "Clearwire4",
            "Contact": null,
            "CommissionPercentage": null,
            "IsActive": true,
            "TimeZone": "Pacific Standard Time",
            "IsEnabled": false,
            "MaxChargePrice": 5,
            "BillingAddress": "Clearwire\r\nPO Box 1726\r\nWoodinv, WA 98072",
            "ShippingAddress": "Clearwire\r\nPO Box 1726\r\nWoodinv, WA 98072",
            "MaximumMeterSalesJumpAllowed": 500,
            "CommissionTerms": "Net10",
            "ExternalAccountTerminalId": null
        }
    ]
}

Response body

// This is a list of the created site's IDs
[
  1673
]

Description

Creates a new Site within a specified Account. Below are the required fields and anything not filled out will be created as null.

Filters Honored

None.

Returns

On Success

The ids of the created sites.

On Error

Update Sites

Request body

{
    "body":
    [
        {
            "Id": 196,
            "AccountId": 11,
            "OrgId": 3,
            "Name": "Clearwire5",
            "Contact": null,
            "CommissionPercentage": null,
            "IsActive": true,
            "TimeZone": "Pacific Standard Time",
            "IsEnabled": false,
            "MaxChargePrice": 5,
            "BillingAddress": "Clearwire\r\nPO Box 1726\r\nWoodinv, WA 98072",
            "ShippingAddress": "Clearwire\r\nPO Box 1726\r\nWoodinv, WA 98072",
            "MaximumMeterSalesJumpAllowed": 500,
            "CommissionTerms": "Net10",
            "ExternalAccountTerminalId": null
        }
    ]
}

Response body

// 204 - No Content

Description

Updates the specified site(s). Below are the required fields and anything not filled out will be created as null. Changes to the isEnabled flag will be disregarded, please use the un/delete routes instead.

Filters Honored

None.

Delete Sites

Request body

{
    "requestFilter": {
        "siteIds": [153]
    }
}

Response body

[
    153
]

Description

Delete the specified site(s).

Filters Honored

• PermissionsFilter
  • siteIds

Returns

On Success

The IDs of the deleted sites.

Undelete Sites

Request body

{
    "requestFilter": {
        "siteIds": [153]
    }
}

Response body

[
    153
]

Description

Undelete the specified site(s).

Filters Honored

• PermissionsFilter
  • siteIds

Returns

On Success

The IDs of the undeleted sites.

Model Definitions

Site Definition

Valid CommissionTerms values:

• PrePaid
• Net10
• Net15
• Net30
• Net45
• Net60

Machines

Get Machines

Request body

{
  "requestFilter": {
    "organizationIds": [],
    "accountIds": [],
    "siteIds": [],
    "machineIdentifiers": [],
    "includeDeleted": false
  }
}

Response body

[
  {
    "id": 1166,
    "assetId": 318,
    "organizationId": 1,
    "siteId": 1,
    "typeId": 0,
    "machineMasterId": 0,
    "forceUpdate": false,
    "prose": null,
    "name": " - ROSEV0000000875",
    "modelNumber": "",
    "taxPercentage": 0.0,
    "commissionPercentage": 0.0,
    "callInCode": "U3EA142DP4",
    "creditProcessingFee": 0.0,
    "bluetoothId": null,
    "externalAccountsTerminalId": 0,
    "createdAt": "2014-08-06T09:56:58.55",
    "provisionedAt": "0001-01-01T00:00:00",
    "canRollbackFirmware": false,
    "ignoreDoorState": false,
    "controllerFirmware": {
      "current": null,
      "pendingUpdate": null
    },
    "pcFirmware": {
      "current": null,
      "pendingUpdate": null
    },
    "hasPlanogramChange": true,
    "enableAccountSales": false,
    "enableCashSales": false,
    "enableCreditSales": false,
    "mode": "unknown",
    "isVisible": true,
    "enableSlotCountTracking": true,
    "useInternetPricing": false,
    "hardwareSettingsChanged": true,
    "usePlangramPrice": false,
    "useMachineTaxRate": false,
    "useMachineCommissionRate": false,
    "lastHeartBeat": {
      "server": "0001-01-01T00:00:00",
      "local": "0001-01-01T00:00:00"
    },
    "lastCashSale": {
      "server": "0001-01-01T00:00:00",
      "local": "0001-01-01T00:00:00"
    },
    "lastCreditSale": {
      "server": "0001-01-01T00:00:00",
      "local": "0001-01-01T00:00:00"
    },
    "lastAccountSale": {
      "server": "0001-01-01T00:00:00",
      "local": "0001-01-01T00:00:00"
    },
    "latestRestockToPicklist": {
      "server": "2015-04-22T10:53:20.883",
      "local": "2015-04-22T10:53:17.617"
    },
    "offerSmsReceipts": 0
  }
]

Description

Retrieves a set of machines.

Filters Honored

• PermissionsFilter
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
  • includeDeleted

Returns

On Success

The requested list of machines.

Get Machine Models

Request body

// N/A

Response body

[
    {
        "id": 1,
        "number": "VCController",
        "description": "VendNovation Controller",
        "supportsAlphaNumericMapping": false
    }
]

Description

Returns a list of machine models.

Filters Honored

None.

Returns

On Success

The list of machine models.

Model Definitions

Machine Definition

Submodels

Here are the definitions of the sub-models used in the machine model.

TimeStamp

FirmwareVersion

Enumerations

Here are the values and meanings of the various enumerations in the machine model.

MachineMode

Default value is purchase.

SmsReceiptMode

Default value is noReceipts.

Machine Model Definition

Selections

Get Selections

Request body

{
  "requestFilter": {
    "organizationIds": [],
    "accountIds": [],
    "siteIds": [],
    "machineIdentifiers": [],
    "selectionIds": [],
    "includeDeleted": false
  }
}

Response body

[
  {
    "id": 3345,
    "machineId": 418,
    "productId": 424,
    "price": 0.7,
    "invoicePrice": 0.0,
    "restockTo": 10,
    "depth": 10,
    "count": 7,
    "isActive": false,
    "alertLevel": null,
    "restockAt": null,
    "freeCount": 0,
    "tax": 0.0,
    "commission": 0.0,
    "selectionNumber": "1",
    "friendlyNumber": "1"
  }
]

Description

Return a list (or a subset) of Organizations the user has access to.

Filters Honored

• PermissionsFilter
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
  • selectionIds
  • includeDeleted

Returns

On Success

The requested set of selections.

Model Definition

Selection Definition

Alerts

Get Alerts

Request body

{
  "routeFilter": {
    "alertIds": [],
    "alertCodes": [],
    "isUserClearable": false,
    "raisedAtStart": "2010-11-12T13:14:15Z",
    "raisedAtEnd": "2010-11-12T13:14:15Z",
    "clearedAtStart": "2010-11-12T13:14:15Z",
    "clearedAtEnd": "2010-11-12T13:14:15Z"
  },
  "requestFilter": {
    "organizationIds": [],
    "accountIds": [],
    "siteIds": [],
    "machineIdentifiers": [],
    "includeDeleted": false
  }
}

Response body

[
  {
    "id": 36578,
    "accountId": 161,
    "siteId": 477,
    "machineLocation": "Lunchroom - Soda",
    "machineProse": null,
    "machineId": 1402,
    "code": "NS",
    "message": "No Sales have been reported by this machine for at least 3 day(s).",
    "isCleared": false,
    "clearedAt": null,
    "raisedAt": "2021-03-29T15:56:41.677"
  }
]

Description

Return a list (or a subset) of Alerts the user has access to.

Filters Honored

• RequestFilter)
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
• AlertFilter
  • alertIds
  • alertCodes
  • isUserClearable
  • raisedAtStart
  • raisedAtEnd
  • clearedAtStart
  • clearedAtEnd

Returns

On Success

The requested set of alerts.

Clear Alerts

Request body

{
  "routeFilter": {
    "alertIds": []
  }
}

Response body

// No respose body

Description

Clear the specified alerts that the user has access to.

Filters Honored

• RequestFilter
  • roleIds
• AlertFilter
  • alertId

Returns

On Error

Model Definitions

Alert Filter

The alerts route takes in an optional object to provide further filtering. Fields and meanings are:

Alert Definition

Reports

Get Transactions

Request body

{
    "requestFilter": {
        "organizationIds": [1],
        "accountIds": [1],
        "siteIds": [1],
        "machineIdentifiers": ["1", "PROSE123456789"],
        "startDate": "2021-11-15T18:07:05.477",
        "endDate": "2021-11-15T18:07:05.477"
    },
    "routeFilter": {
        "transactionIdentifiers": ["B1488"]
    }
}

Response body

[
    {
        "id": "B1467",
        "recordedAtUtc": "2021-11-16T22:51:35.16",
        "siteId": 1658,
        "siteExternalId": "",
        "siteName": "Khadeer 1",
        "machineId": 11252,
        "machineExternalId": null,
        "machineName": "Khadeer Machine 1",
        "machineModel": "VCController_10_10_69",
        "totalPrice": 1.0000,
        "totalTax": 0.0,
        "lineItems": [
            {
                "id": 3527998,
                "selection": "10",
                "vendOrder": 1,
                "productId": 18333,
                "productName": "Chicken",
                "productUpc": "9046d33f79574eb9af9abf827e6c292d",
                "size": "1 fl. oz.",
                "taxRate": 0.0,
                "taxCharged": 0.0,
                "commission": 0.0,
                "quantity": 1,
                "unitPrice": 1.0000,
                "totalPrice": 1.0000,
                "vendWasSuccessful": true,
                "recordedAtUtc": "2021-11-16T22:51:35.193",
                "occurredAtUtc": "2021-11-16T22:51:31",
                "occurredAtLocalTime": "2021-11-16T10:51:31"
            }
        ],
        "paymentInformation": {
            "type": "A ",
            "creditInformation": {
                "gateway": "A",
                "invoiceNumber": 511005,
                "cardToken": null,
                "authorizationNumber": null,
                "referenceNumber1": "",
                "referenceNumber2": null,
                "paymentStatus": "charged"
            },
            "accountInformation": {
                "accountNumber": "1234",
                "nameOnAccount": "Bobbin Bob"
            }
        }
    }
]

Description

Retrieves a set of transactions.

Note that your datetime filters will be clamped to a maximum range of a month following the processes laid out in DateTime Handling. Page sizes larger than 100 will be clamped down for performance reasons.

Filters Honored

• RequestFilter
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
  • startDate
  • endDate
• TransactionFilter
  • transactionIdentifiers

Returns

On Success

The requested list of transactions.

Get Transaction Metadata

Request body

{
    "requestFilter": {
        "organizationIds": [1],
        "accountIds": [1],
        "siteIds": [1],
        "machineIdentifiers": ["1", "PROSE123456789"],
        "startDate": "2021-11-15T18:07:05.477",
        "endDate": "2021-11-15T18:07:05.477"
    },
    "routeFilter": {
        "transactionIds": ["B1488"]
    }
}

Response body

[
    {
        "transactionId": "B1467",
        "recordedAtUtc": "2021-11-16T22:51:35.16",
        "tags": [],
        "files": [],
        "lineItems": [
            {
                "lineItemId": 3527998,
                "recordedAtUtc": "2021-11-16T22:51:35.193",
                "occurredAtUtc": "2021-11-16T22:51:31",
                "occurredAtLocal": "2021-11-16T10:51:31",
                "tags": [],
                "files": []
            }
        ]
    }
]

Description

Retrieves a set of transaction metadata.

Note that your datetime filters will be clamped to a maximum range of a month following the processes laid out in DateTime Handling. Page sizes larger than 100 will be clamped down for performance reasons.

Filters Honored

• RequestFilter
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
  • startDate
  • endDate
• TransactionFilter
  • transactionIdentifiers

Returns

On Success

The requested list of transactions.

Get Inventory Adjustment Events

Request body

{
    "requestFilter": {
        "organizationIds": [1],
        "accountIds": [1],
        "siteIds": [1],
        "machineIdentifiers": ["1", "PROSE123456789"],
        "startDate": "2021-11-15T18:07:05.477",
        "endDate": "2021-11-15T18:07:05.477"
    },
    "routeFilter": {
        "transactionIds": ["B1488"]
    }
}

Response body

[
    {
        "id": "B1625",
        "adjustmentOccurredAt": "2021-12-15T01:11:24.36",
        "takeOccurredAt": "2021-12-15T01:11:24",
        "siteId": 567,
        "siteExternalId": "babc188c-a1e5-4ea2-9648-93dbd8c422dd",
        "machineId": "11398",
        "machineExternalId": null,
        "selection": "132",
        "productId": "49998",
        "userId": 0,
        "externalUserIdentifier": null,
        "adjustmentSize": 1,
        "newStockLevel": 83
    }
]

Description

Retrieves a set of inventory adjustment events.

Note that your datetime filters will be clamped to a maximum range of a month following the processes laid out in DateTime Handling.

Filters Honored

• RequestFilter
  • organizationIds
  • accountIds
  • siteIds
  • machineIdentifiers
  • startDate
  • endDate
• TransactionFilter
  • transactionIdentifiers

Returns

On Success

The requested list of inventory adjustment events.

Model Definitions

Transaction Definition

Unless otherwise stated. Data reflects values as of time of data retrieval, not at time of transaction.

Line Item Definition

Unless otherwise stated. Data reflects values as of time of data retrieval, not at time of transaction.

Payment Information Definition

Credit Information Definition

Account Information Definition

Transaction Metadata

Tag Definition

File Definition

LineItemMetadata Definition

Transaction Filter

Inventory Adjustment Event Definition

Products

Get Products

Request body

{
  "requestFilter": {
    "organizationIds": [],
    "productIds": []
  }
}

Response body

[
    {
        "productId": 967,
        "manufacturer": "Dixie",
        "brand": "Dixie",
        "name": "\"5 7/8\" Plates\"",
        "customData": null,
        "size": 250.0,
        "unitsForSize": "cnt",
        "container": null,
        "upc": null,
        "productImage": null,
        "nutritionImage": null,
        "cost": 11.3500,
        "defaultPrice": 0.0,
        "isACommonProduct": true,
        "vendSize": null,
        "calories": 864,
        "productGroup": "Coffee - Allied"
    }
]

Description

Return a list (or a subset) of Products the user has access to.

Filters Honored

• PermissionsFilter
  • organizationIds
  • productIds

Returns

On Success

The requested set of products.

Model Definitions

Product Definition

Product Enumerations

Container

Default value is unknown.

VendSize

Default value is unknown.

Templates

Get Templates

Request body

{
    "requestFilter": {
      "organizationsId": [1]
    },
    "routeFilter": {
      "templateIds": [1, 2, 3],
      "templateGroupIds": [1]
    }
}

Response body

[
    {
        "id": 391,
        "organizationId": 1,
        "name": "name",
        "comment": "desc",
        "count": 0,
        "machineId": null,
        "createdAt": "2021-08-13T14:11:39.41"
    }
]

Description

Get a list (or subset) of Templates belonging to an Organization.

Filters Honored

• RequestFilter
  • organizationIds
• TemplatingFilter
  • templateIds
  • templateGroupIds

Returns

On Success

The requested set of templates.

Create Template

Request body

{
    "body": [
        {
            "organizationId": 1,
            "name": "create test",
            "comment": null,
            "count": 0,
            "machineId": null
        }
    ]
}

Response body

// list of ids for created templates
[
  6
]

Description

Creates the specified templates.

Filters Honored

None.

Returns

On Success

The ID of the created templates.

Update Templates

Request body

{
    "body": [
        {
            "id": 406,
            "name": "create test",
            "comment": "updated comment",
            "count": 0,
            "machineId": null
        }
    ]
}

Response body

// echo back of the models you sent
[
    {
        "id": 406,
        "name": "create test",
        "comment": "updated comment",
        "count": 0,
        "machineId": null
    }
]

Description

Updates the specified template(s).

Filters Honored

None.

Delete Template

Request body

{
    "routeFilter": {
        "templateIds": [4]
    }
}

Response body

// 204 - No Content

Description

Deletes the specified template(s).

Filters Honored

• TemplatingFilter
  • templateIds

Apply Template to Machines

Request body

{
    "requestFilter":{
        "machineIdentifiers": ["3533", "PROSE0123456789"]
    },
    "routeFilter": {
        "templateIds": [412]
    }
}

Response body

// 204 - No Content

Description

Apply the specified template to the specified machines. You MUST specifiy at least one template and one machine, and the template and all the machines must belong to the same organizaiton.

Filters Honored

• TemplatingFilter
  • templateIds
• RequestFilter
  • machineIdentifiers

Returns

On Error

Model Definitions

Template Definition

Template Groups

Get Template Groups

Request body

{
    "requestFilter": {
      "organizationsId": [1]
    },
    "routeFilter": {
      "templateGroupIds": [1]
    }
}

Response body

[
    {
        "id": 6,
        "name": "Standard",
        "description": "Default Template Group",
        "createdAt": "2021-09-09T15:02:37.403",
        "organizationId": 25
    }
]

Description

Get a list (or subset) of template groups.

Filters Honored

• RequestFilter
  • organizationIds
• TemplatingFilter
  • templateGroupIds

Returns

On Success

The requested set of template groups.

Create Template Groups

Request body

{
    "body": [
        {
            "name": "create",
            "description": null,
            "organizationId": 1
        }
    ]
}

Response body

// list of ids for created templates
[
  6
]

Description

Creates the specified template group(s).

Filters Honored

None.

Returns

On Success

A list of id(s) representing the created template group(s).

Update Template Groups

Request body

{
    "body": [
        {
        "id": 3,
        "name": "create",
        "description": "updated description",
        "organizationId": 1
        }
    ]
}

Response body

// echo back of the models you sent
[
    [
        {
        "id": 3,
        "name": "create",
        "description": "updated description",
        "organizationId": 1
        }
    ]
]

Description

Updates the specified template group(s).

Filters Honored

None.

Returns

On Success

The updated template group(s).

Delete Template Groups

Request body

{
    "routeFilter": {
        "templateGroupIds": [4]
    }
}

Response body

// 204 - No Content

Description

Deletes the specified template group(s).

Filters Honored

• TemplatingFilter
  • templateGroupIds

Assign Machines to Template Groups

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["5590"]
    },
    "routeFilter": {
        "templateGroupIds": [7]
    }
}

Response body

// 204 - No Content

Description

Assign one or more machines to a template group. Note, you MUST supply one and ONLY one template group id.

Filters Honored

• RequestFilter
  • machineIdentifiers
• TemplatingFilter
  • templateGroupIds

Remove Machines from Template Group

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["5590"]
    },
    "routeFilter": {
        "templateGroupIds": [7]
    }
}

Response body

// 204 - No Content

Description

Remove one or more machines from a template group. Note, you MUST supply one and ONLY one template group id.

Filters Honored

• RequestFilter
  • machineIdentifiers
• TemplatingFilter
  • templateGroupIds

Assign Templates to Template Group

Request body

{
    "routeFilter": {
        "templateIds": [7],
        "templateGroupIds": [1]
    }
}

Response body

// 204 - No Content

Description

Assign one or more templates to a template group. This is a many-to-many assignment with all templates being assigned to all specified template groups, however all specified templates and template groups must belong to the specified organization.

Filters Honored

• TemplatingFilter
  • templateIds
  • templateGroupIds

Remove Templates from Template Group

Request body

{
    "routeFilter": {
        "templateIds": [1],
        "templateGroupIds": [7]
    }
}

Response body

// 204 - No Content

Description

Remove one or more templates from a template group. Note, you MUST supply one and ONLY one template group id.

Filters Honored

• TemplatingFilter
  • templateIds
  • templateGroupIds

Get Template Group to Template Links

Request body

{
    "routeFilter": {
        "templateIds": [1],
        "templateGroupIds": [7]
    }
}

Response body

[
    {
        "roleId": 7,
        "machineId": 0,
        "createdAt": "2021-09-14T18:39:27.747"
    }
]

Description

Returns a list of links between template groups and templates.

Filters Honored

• TemplatingFilter
  • templateIds
  • templateGroupIds

Returns

On Success

A list of TemplateGroupToTemplateLinks.

Model Definitions

Template Group Definition

TemplateGroupToTemplateLink Definition

Template Selections

Get Template Selections

Request body

{
    "requestFilter": {
      "organizationsId": [1]
    },
    "routeFilter": {
      "templateIds": [1, 2, 3],
      "templateSelectionIds": [1]
    }
}

Response body

[
    {
        "id": 0,
        "variantId": null,
        "templateId": 408,
        "selectionNumber": 1,
        "productId": 44787,
        "price": 0.1000,
        "invoicePrice": 0.0000,
        "par": 10,
        "depth": 0,
        "commission": 0.0,
        "tax": 0.0,
        "customData1": null,
        "customData2": null,
        "customData3": null,
        "customData4": null,
        "customData5": null
    }
]

Description

Retrieve a set template selections belonging to an Organization.

Filters Honored

• RequestFilter
  • organizationIds
• TemplatingFilter
  • templateIds
  • templateSelectionIds

Returns

On Success

The requested set of set template selections.

Create Template Selections

Request body

{
    "body": [
        {
            "templateId": 2,
            "selectionNumber": 0,
            "productId": 0,
            "price": 0.0,
            "invoicePrice": 0.0,
            "par": 0,
            "depth": 0,
            "comission": null,
            "tax": null,
            "customData1": null,
            "customData2": null,
            "customData3": null,
            "customData4": null,
            "customData5": null
        }
    ]
}

Response body

// list of ids for created template selections
[
  6
]

Description

Creates the specified template selection(s).

Filters Honored

None.

Returns

On Success

The IDs of the created template selection(s).

Update Template Selections

Request body

{
    "body": [
        {
            "id": 11242,
            "templateId": 2,
            "selectionNumber": 0,
            "productId": 0,
            "price": 6.9,
            "invoicePrice": 0.0,
            "par": 0,
            "depth": 0,
            "comission": null,
            "tax": null,
            "customData1": null,
            "customData2": null,
            "customData3": null,
            "customData4": null,
            "customData5": null
        }
    ]
}

Response body

// the updated template selections
[
    {
        "id": 11242,
        "templateId": 2,
        "selectionNumber": 0,
        "productId": 0,
        "price": 6.9,
        "invoicePrice": 0.0,
        "par": 0,
        "depth": 0,
        "comission": null,
        "tax": null,
        "customData1": null,
        "customData2": null,
        "customData3": null,
        "customData4": null,
        "customData5": null
    }
]

Description

Updates the specified template selection(s).

Filters Honored

None.

Returns

On Success

The updated template selections.

Delete Template Selections

Request body

{
    "routeFilter": {
        "templateSelectionIds": [4]
    }
}

Response body

// 204 - No Content

Description

Deletes the specified template selection(s).

Filters Honored

• TemplatingFilter
  • templateSelectionIds

Model Definitions

Template Selection Definition

Roles

Get Roles

Request body

{
    "requestFilter": {
      "organizationsId": [2]
    },
    "routeFilter": {
      "roleIdentifiers": [1, "test-role"]
    }
}

Response body

[
  {
      "organizationId": 2,
      "id": 5,
      "name": "create test",
      "description": "create test description"
  }
]

Description

Retrieve a set of roles.

Filters Honored

• RequestFilter
  • organizationIds
• PermissionsFilter
  • roleIdentifiers

Returns

On Success

The requested set of roles.

Create Roles

Request body

{
    "body": [
        {
            "organizationId": 2,
            "name": "create test",
            "description": "create test description"
        }
    ]
}

Response body

// list of ids for created roles
[
  6
]

Description

Creates the specified Roles.

Filters Honored

None.

Returns

On Success

The IDs of the created roles.

Update Roles

Request body

{
    "body": [
        {
            "roleId": 2,
            "name": "update test",
            "description": "update test description"
        }
    ]
}

Response body

// echo back of the models you sent
[
    {
        "roleId": 2,
        "name": "update test",
        "description": "update test description"
    }
]

Description

Updates the specified roles.

Filters Honored

None.

Delete Roles

Request body

{
    "routeFilter": {
        "roleIdentifiers": [4]
    }
}

Response body

// 204 - No Content

Description

Deletes the specified roles.

Filters Honored

• PermissionsFilter
  • roleIdentifiers

Check Role's Machine Access

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["3283"]
    },
    "routeFilter": {
        "roleIdentifiers": [4]
    }
}

Response body

[
    {
        "roleName": "name",
        "roleId": 0,
        "prose": "PROSE012346789", // will be null if you specified an id for this machine
        "machineId": 0, // will always be present
        "canAccess": false
    }
]

Description

Given a list of machine identifiers and a list of role names (or IDs), return a list of MachineAccessResponses (one per each unique role ID/name and machine combo) indicating if each role has access to each machine.

Filters Honored

• RequestFilter)
  • machineIdentifiers
• PermissionsFilter
  • roleIdentifiers

Returns

On Success

A list of role to machine mappings with a boolean indicating if that role can access that machine.

Get Role's Rights at Machine

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["3283"]
    },
    "routeFilter": {
        "roleIdentifiers": [4]
    }
}

Response body

{
  "1": [1, 2, 3]
}

Description

Given a list of machine identifiers and a list of role names (or IDs), returns the cumulative list of all rights granted by all the specified roles, at the specified machine.

Filters Honored

• RequestFilter)
  • machineIdentifiers
• PermissionsFilter
  • roleIdentifiers

Returns

On Success

Return format is Dictionary<int, List<int>>, where the key is the machine ID and the list is the granted right IDs.

Assign Role To Machine

Request body

{
    "requestFilter": {
        "organizationIds": [],
        "machineIdentifiers": ["3283"]
    },
    "routeFilter": {
        "roleIdentifiers": [1, 2, 3]
    }
}

Response body

// 204

Description

Assign one or more roles to one or more machines. All roles and machines must belong to the same organization.

Filters Honored

• RequestFilter)
  • machineIdentifiers
• PermissionsFilter
  • roleIdentifiers

Unassign Roles from Machines

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["3283"]
    },
    "routeFilter": {
        "roleIdentifiers": [4]
    }
}

Response body

// No content

Description

Unassign one or more roles from one or more machines. All roles and machines must be in the same organization.

Filters Honored

• RequestFilter
  • machineIdentifiers
• PermissionsFilter
  • roleIdentifiers

Get Role to Machine Links

Request body

{
    "requestFilter": {
        "machineIdentifiers": ["3283"]
    },
    "routeFilter": {
      "roleIdentifiers": [  1, 2, 3 ]
    }
}

Response body

[
    {
        "roleId": 3,
        "machineId": 3283,
        "createdAt": "2021-11-01T23:56:57.22"
    },
    {
        "roleId": 2,
        "machineId": 3283,
        "createdAt": "2021-11-01T23:56:57.22"
    },
    {
        "roleId": 1,
        "machineId": 3283,
        "createdAt": "2021-11-01T23:56:57.217"
    }
]

Description

Returns a list of links between machines and roles.

Filters Honored

• RequestFilter)
  • machineIdentifiers
• PermissionsFilter
  • roleIdentifiers

Returns

On Success

A list of RoleToMachineLinks.

Model Definitions

Role Definition

RoleToMachineLink Definition

Role Rights

Role rights link user defined roles to statically defined rights.

Get Role Rights

Request body

{
    "requestFilter": {
      "organizationsId": [2]
    },
    "routeFilter": {
      "roleRightIds": [1, 2]
    }
}

Response body

[
    {
        "id": 0,
        "roleId": 0,
        "rightId": 0,
        "canView": false,
        "canEdit": false,
        "canExecute": false
    }
]

Description

Retrieve a set of role rights.

Filters Honored

• RequestFilter
  • organizationIds
• PermissionsFilter
  • roleRightIds

Returns

On Success

The requested set of role rights.

Create Role Rights

Request body

{
    "body": [
            {
                "roleId": 0,
                "rightId": 0,
                "canView": false,
                "canEdit": false,
                "canExecute": false
            }
    ]
}

Response body

// list of ids for created roles
[
  6
]

Description

Creates the specified role right(s).

Filters Honored

None.

Returns

On Success

• 200 - A list of IDs belonging to the created role rights.

Update Role Rights

Request body

{
    "body": [
          {
             "id": 0,
              "canView": false,
              "canEdit": false,
              "canExecute": false
          }
    ]
}

Response body

// echo back of the models you sent
[
    {
       "id": 0,
        "canView": false,
        "canEdit": false,
        "canExecute": false
    }
]

Description

Updates the specified Role Rights. Note that if you set all three permissions to false your role right will instead be deleted resulting in a smaller result set than you might expect.

Filters Honored

None.

Delete Role Rights

Request body

{
    "routeFilter": {
        "roleRightIds": [4]
    }
}

Response body

// 204 - No Content

Description

Deletes the specified Role Rights.

Filters Honored

• PermissionsFilter
  • roleRightIds

Model Definitions

Role Right Definition

Rights

Get Rights

Request body

{
    "routeFilter": {
      "roleIdentifiers": [1, "test-role"],
      "rightIds": [1]
    }
}