Nuvias Logo
Documentation Powered by ReDoc

Hub API (1.1.0)

Download OpenAPI specification:Download

Support: support@nuvias-uc.com URL: https://support.nuvias-uc.com License: TBC Terms of Service

The Hub API is a REST API which provides access to all of Nuvias Hub functions for customers to use.

Introduction

This API provides access to all of the functions normally available in Hub.

Note : Access to Hub API requires that you have a credit account with Nuvias UC and are a reseller or service provider entitled to purchase from distribution. For more information on setting up an account, see this page.

The API has predictable resource-oriented URLs, accepts only JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication and verbs.

You can use this API, subject to the terms below, to access your data in Hub and perform the actions you normally would be able to based on your access permissions.

Versioning

We subscribe to the principles of semantic versioning. Patch and minor releases are backwardly compatible, but this does require you to be flexible in handling our API - we may add optional fields to endpoints or add additional data in a response as part of a minor release.

You can access specific versions of the API by specifying the version as part of the path.

Older versions of the API are available for at least 6 months after the release of a new version although we may extend this in some circumstances.

Multi-tier

Hub is multi-tier so you can represent your descendant organisations (e.g. customers or resellers) in Hub and allow them to perform actions. Access to data in Hub is determined by the organisation that you authenticate as

When describing multi-tier operations:

  • Parent: The direct parent of the organisation
  • Ancestor: Any parent, grand-parent or so on
  • Child: The direct child of an organisation
  • Descendant: Any child, grand-child and so on

For example: In the following organisation chain A > B > C > D > E: B is the parent of C, A and B are the ancestors of C, D is the child of C, D and E are the descendants of C.

Branding

We offer this API as a whitelabel service to our customers. If you're interested in this, get in touch with your account manager.

Getting help

The API is provided without formal support, however we have put together some resources to help.

First of all, check our Developer site where we publish the latest information and help available to developers, including the latest release notes.

You can also log in to Hub itself an review how the user interface works - the API is developed alongside the interface and so you can see how we're using the API and the data.

Authentication

The Hub API uses OAuth 2.0 as an authentication mechanism. To use the API you must first create an API client through the web interface for the user you wish to authenticate as. When this is complete, a Client ID and Client Secret will be displayed - please note the Secret is only displayed once.

Hub uses the Client Credentials Grant Type, requiring the API client to send a POST request to the token endpoint, along with the client ID and secret as described here. This endpoint then returns an access token and expiry time.

Subsequent requests to the API should then use the token in the Authorization header of the request in the format Authorization: Bearer thesecretapitoken.

OAuth2

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /api/v1/oauth/create_token
Scopes:

    OAuth

    OAuth tokens are used for authenticating a client to use the Hub API.

    Create OAuth token

    Creates OAuth token from API client credentials. This OAuth token can then be used to access the rest of the API.

    Request Body schema: application/x-www-form-urlencoded
    client_id
    required
    string

    API client ID (UUID)

    client_secret
    required
    string

    API client secret

    grant_type
    required
    string
    Value: "client_credentials"

    Grant type, currently only client credentials supported

    Responses

    Request samples

    Content type
    application/x-www-form-urlencoded
    client_id=123e4567-e89b-12d3-a456-426614174000&client_secret=abcdefgh1234567&grant_type=client_credentials

    Response samples

    Content type
    application/json
    {
    • "access_token": "abc123",
    • "token_type": "Bearer",
    • "expires_in": 3600
    }

    Who am I?

    The whoami API is used to determine information about the logged in user.

    Get authenticated user

    Gets details about the currently authenticated user. If emulation is in progress, then all returned information (other than the real_id and real_name) will be about the emulated user.

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 5,
    • "name": "Tom Jones",
    • "organisation": 5,
    • "real_id": 1,
    • "real_name": "Diana Ross",
    • "currency": "GBP",
    • "locale": "en",
    • "timezone": "Europe/London",
    • "admin": false,
    • "root": false,
    • "modules": [
      ],
    • "permissions": [
      ]
    }

    Organisations

    Organisations represent companies in a multi-tiered structure.

    Get organisations

    Gets a list of organisations

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get organisation addresses

    Get list of saved addresses for organisation

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Users

    Users contains the relevant personal settings and permissions of a person using Hub

    Get users

    Gets a list of users on hub

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    text
    string
    Example: text=example@example.com

    Filter users by name or email address

    organisation
    Array of integers
    Example: organisation=1

    Filter by a list of organisation IDs

    verified
    boolean
    Example: verified=false

    Filter by a list of verified/unverified users

    disabled
    boolean
    Example: disabled=true

    Filter by a list of disabled/enabled users

    password_reset
    boolean
    Example: password_reset=true

    Filter by a list of password reset requested users

    sort_by
    Array of strings
    Default: "-name"
    Items Enum: "-name" "+name" "-email_address" "+email_address"
    Example: sort_by=+name

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get user by ID

    Retrieves a user by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the user

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 0,
    • "name": "Evan Evans",
    • "email_address": "evan.evans@organisation.com",
    • "organisation": 1,
    • "admin": true,
    • "two-factor": true,
    • "active": true,
    • "verified": true,
    • "password_reset": true,
    • "user_language": "en",
    • "timezone": "UTC",
    • "timeout": 86400,
    • "roles": [
      ],
    • "notification": [
      ],
    • "api_clients": [
      ],
    • "audit_logs": [
      ],
    • "actions_taken": [
      ]
    }

    Create a new user

    Create a new user

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the user

    Request Body schema: application/json
    name
    string

    Name of the user

    email_address
    string

    Email address of the user

    organisation
    integer

    ID of the organisation user belongs to, PLEASE NOTE changing the organisation on a PUT request resets roles and notifications

    admin
    boolean

    whether the user has administrator privelidges

    two-factor
    boolean

    true if user has enabled 2-factor authentication, false otherwise

    active
    boolean

    false if user has been disabled, true otherwise

    verified
    boolean

    false if account has not been verified, true otherwise

    password_reset
    boolean

    true if user is required to reset their password, false otherwise

    user_language
    string
    Enum: "de" "en" "es" "fr" "it" "nl"

    default language to display in Hub

    timezone
    string

    timezone the user wants dates and times to be displayed in

    timeout
    integer
    Enum: 86400 43200 28800 14400 7200 3600 1800

    number of seconds of user inactivity before user is automatically logged out

    roles
    Array of integers

    list of Roles that this user has been assigned, PLEASE NOTE on a PUT request this overwrites previously held roles for the user

    notification
    Array of strings
    Items Enum: "buy_price_increased" "checkout_requested" "order_created" "order_requires_manual_auth" "order_status_changed" "quote_amended" "quote_created"

    list of Notifications that this user has been assigned, PLEASE NOTE on a PUT request this overwrites previously held notifications for the user

    Array of objects (APIClient)

    list of API Client details for the user

    Array of objects (AuditLog)

    list of audit log entries associated to this user

    Array of objects (AuditLog)

    list of audit log entries that have occured as a result of this user's actions

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Evan Evans",
    • "email_address": "evan.evans@organisation.com",
    • "organisation": 1,
    • "admin": true,
    • "two-factor": true,
    • "active": true,
    • "verified": true,
    • "password_reset": true,
    • "user_language": "en",
    • "timezone": "UTC",
    • "timeout": 86400,
    • "roles": [
      ],
    • "notification": [
      ],
    • "api_clients": [
      ],
    • "audit_logs": [
      ],
    • "actions_taken": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "id": 0,
    • "name": "Evan Evans",
    • "email_address": "evan.evans@organisation.com",
    • "organisation": 1,
    • "admin": true,
    • "two-factor": true,
    • "active": true,
    • "verified": true,
    • "password_reset": true,
    • "user_language": "en",
    • "timezone": "UTC",
    • "timeout": 86400,
    • "roles": [
      ],
    • "notification": [
      ],
    • "api_clients": [
      ],
    • "audit_logs": [
      ],
    • "actions_taken": [
      ]
    }

    Edit user by ID

    Used to edit a user by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the user

    Request Body schema: application/json
    name
    string

    Name of the user

    email_address
    string

    Email address of the user

    organisation
    integer

    ID of the organisation user belongs to, PLEASE NOTE changing the organisation on a PUT request resets roles and notifications

    admin
    boolean

    whether the user has administrator privelidges

    two-factor
    boolean

    true if user has enabled 2-factor authentication, false otherwise

    active
    boolean

    false if user has been disabled, true otherwise

    verified
    boolean

    false if account has not been verified, true otherwise

    password_reset
    boolean

    true if user is required to reset their password, false otherwise

    user_language
    string
    Enum: "de" "en" "es" "fr" "it" "nl"

    default language to display in Hub

    timezone
    string

    timezone the user wants dates and times to be displayed in

    timeout
    integer
    Enum: 86400 43200 28800 14400 7200 3600 1800

    number of seconds of user inactivity before user is automatically logged out

    roles
    Array of integers

    list of Roles that this user has been assigned, PLEASE NOTE on a PUT request this overwrites previously held roles for the user

    notification
    Array of strings
    Items Enum: "buy_price_increased" "checkout_requested" "order_created" "order_requires_manual_auth" "order_status_changed" "quote_amended" "quote_created"

    list of Notifications that this user has been assigned, PLEASE NOTE on a PUT request this overwrites previously held notifications for the user

    Array of objects (APIClient)

    list of API Client details for the user

    Array of objects (AuditLog)

    list of audit log entries associated to this user

    Array of objects (AuditLog)

    list of audit log entries that have occured as a result of this user's actions

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Evan Evans",
    • "email_address": "evan.evans@organisation.com",
    • "organisation": 1,
    • "admin": true,
    • "two-factor": true,
    • "active": true,
    • "verified": true,
    • "password_reset": true,
    • "user_language": "en",
    • "timezone": "UTC",
    • "timeout": 86400,
    • "roles": [
      ],
    • "notification": [
      ],
    • "api_clients": [
      ],
    • "audit_logs": [
      ],
    • "actions_taken": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "id": 0,
    • "name": "Evan Evans",
    • "email_address": "evan.evans@organisation.com",
    • "organisation": 1,
    • "admin": true,
    • "two-factor": true,
    • "active": true,
    • "verified": true,
    • "password_reset": true,
    • "user_language": "en",
    • "timezone": "UTC",
    • "timeout": 86400,
    • "roles": [
      ],
    • "notification": [
      ],
    • "api_clients": [
      ],
    • "audit_logs": [
      ],
    • "actions_taken": [
      ]
    }

    Products

    Products are the items that can be purchased through Hub.

    Get product groups

    Returns a list of ProductGroupInfo objects

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Create a new product group

    Create a new product group

    Authorizations:
    OAuth2
    Request Body schema: application/json
    name
    string

    Name of ProductGroup

    active
    boolean

    True is product group is available for purchase, false if discontinued

    status
    string
    Enum: "DRAFT" "LIVE"

    Field indicates if ProductGroup is in Draft or Live (ready for sale)

    description
    string

    Description of ProductGroup

    detailed_description
    string

    Detailed description of the ProductGroup

    type
    integer

    The ID of the associated ProductType

    vendor
    integer

    The ID of the associated Vendor

    subscription_type
    string
    Enum: "DROPBOX" "ACRONIS" "ZOOM"

    If this is a product group for subscriptable products, this is the type of associated subscription

    subscription_product_type
    string
    Enum: "BASE" "ADD_ON"

    If this product group has a subscription type, this indicates if the group contains BASE or ADDON products

    products
    Array of integers

    list of products associated with this ProductGroup

    related_product_groups
    Array of integers

    list of product grouping IDs related to this ProductGroup

    grading
    integer

    An arbitrary integer that can be set on product group to indicate a ranking or heirarchy of the product group relative to others in a context-sensitive manner

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Phone Starter Bundle",
    • "active": true,
    • "status": "DRAFT",
    • "description": "Phone Starter Bundle is a great starter bundle",
    • "detailed_description": "Phone Starter Bundle contains a Phone, wall-mounting kit, extension cable, Hands-free headset and cleaning cloth",
    • "type": 10,
    • "vendor": 10,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "products": [
      ],
    • "related_product_groups": [
      ],
    • "grading": 12
    }

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "Phone Starter Bundle",
    • "active": true,
    • "status": "DRAFT",
    • "description": "Phone Starter Bundle is a great starter bundle",
    • "detailed_description": "Phone Starter Bundle contains a Phone, wall-mounting kit, extension cable, Hands-free headset and cleaning cloth",
    • "type": 10,
    • "vendor": 10,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "products": [
      ],
    • "related_product_groups": [
      ],
    • "grading": 12
    }

    Get a single product group by ID

    Returns a ProductGroup object

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the product group

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "Phone Starter Bundle",
    • "active": true,
    • "status": "DRAFT",
    • "description": "Phone Starter Bundle is a great starter bundle",
    • "detailed_description": "Phone Starter Bundle contains a Phone, wall-mounting kit, extension cable, Hands-free headset and cleaning cloth",
    • "type": 10,
    • "vendor": 10,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "products": [
      ],
    • "related_product_groups": [
      ],
    • "grading": 12
    }

    Edit product group by ID

    Used to edit a product group by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the product group

    Request Body schema: application/json
    name
    string

    Name of ProductGroup

    active
    boolean

    True is product group is available for purchase, false if discontinued

    status
    string
    Enum: "DRAFT" "LIVE"

    Field indicates if ProductGroup is in Draft or Live (ready for sale)

    description
    string

    Description of ProductGroup

    detailed_description
    string

    Detailed description of the ProductGroup

    type
    integer

    The ID of the associated ProductType

    vendor
    integer

    The ID of the associated Vendor

    subscription_type
    string
    Enum: "DROPBOX" "ACRONIS" "ZOOM"

    If this is a product group for subscriptable products, this is the type of associated subscription

    subscription_product_type
    string
    Enum: "BASE" "ADD_ON"

    If this product group has a subscription type, this indicates if the group contains BASE or ADDON products

    products
    Array of integers

    list of products associated with this ProductGroup

    related_product_groups
    Array of integers

    list of product grouping IDs related to this ProductGroup

    grading
    integer

    An arbitrary integer that can be set on product group to indicate a ranking or heirarchy of the product group relative to others in a context-sensitive manner

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Phone Starter Bundle",
    • "active": true,
    • "status": "DRAFT",
    • "description": "Phone Starter Bundle is a great starter bundle",
    • "detailed_description": "Phone Starter Bundle contains a Phone, wall-mounting kit, extension cable, Hands-free headset and cleaning cloth",
    • "type": 10,
    • "vendor": 10,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "products": [
      ],
    • "related_product_groups": [
      ],
    • "grading": 12
    }

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "Phone Starter Bundle",
    • "active": true,
    • "status": "DRAFT",
    • "description": "Phone Starter Bundle is a great starter bundle",
    • "detailed_description": "Phone Starter Bundle contains a Phone, wall-mounting kit, extension cable, Hands-free headset and cleaning cloth",
    • "type": 10,
    • "vendor": 10,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "products": [
      ],
    • "related_product_groups": [
      ],
    • "grading": 12
    }

    Get products

    Retrieve a list of products, paginated according to the per_page attribute. You can use a combination of the attributes in any way to filter the list.

    Note that the text parameter allows you to specify a string with which to search against the product name and also the product code or SKU. To retrieve the ID of a product if you know its SKU, simply use the text parameter with the SKU. Note that SKU or product code is not guaranteed to be unique across multiple vendors.

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    vendor
    Array of integers
    Example: vendor=5

    Filter by an array of vendor IDs. -1 can be used to filter by records with no vendor assigned

    type
    Array of integers
    Example: type=10

    Filter by an array of product type IDs. -1 can be used to filter by records with no product type

    text
    string
    Example: text=2200-123-123

    Filter by name or product code

    sort_by
    Array of strings
    Default: "-popularity"
    Items Enum: "-popularity" "-name" "+name" "-price" "+price"
    Example: sort_by=-popularity

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get product by ID

    Gets a product by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of product

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "name": "A New Phone",
    • "product_code": "NEW-PH0N3",
    • "description": "100 Lines, Full Colour, Makes Toast Too",
    • "detailed_description": "This phone is everything you need in a new device. It makes toast, orders lunch, and even has been known to save lives*\n*T&Cs apply",
    • "featured_description": "100 lines\nFull colour screen\nIn-built toaster",
    • "vendor": 5,
    • "type": 10,
    • "rrp": 110.12,
    • "price": 100.12,
    • "thumb_url": "string",
    • "main_image_url": "string",
    • "datasheet_url": "string",
    • "guide_url": "string",
    • "quickstart_url": "string",
    • "stock": 9001,
    • "provisioning": [
      ],
    • "maintenance": [
      ],
    • "related_to": [
      ],
    • "shipping_cost": 20,
    • "show_in_webstore": false,
    • "discountable": false,
    • "subscription_type": "DROPBOX",
    • "subscription_product_type": "BASE",
    • "quantity_type": "QUANTITY",
    • "rate_plans": [
      ],
    • "is_shippable": false,
    • "is_financeable": false,
    • "weight_unit": "GRAMS",
    • "weight": 12.45
    }

    Get product types

    Gets the list of product types used by Hub. Product types are used to categorise products to better aid in filtering.

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Baskets

    Baskets are the basic objects for placing orders in Hub and can be used to provide a preview of the order prior to submitting. Basket attributes carry over to the order. Basket objects are a limited version of the Order object, represented internally as an Order in a DRAFT state.

    Get baskets

    Gets baskets for own organisation.

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    sort_by
    Array of strings
    Default: "+name"
    Items Enum: "-name" "-total" "+name" "+total"
    Example: sort_by=+name

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create basket

    Creates a new basket

    Authorizations:
    OAuth2
    Request Body schema: application/json
    purchase_order_number
    string

    The user-supplied purchase order identifier

    object (Address)

    An address in Hub represents a physical location. It is used for shipping and for Dovetail sites.

    shipping_type
    integer

    The ID of the Shipping Type of this order

    ship_instructions
    string <= 3500 characters

    Any shipping instructions that have been provided with this order

    end_user
    string

    The End User that this order is for, or zoom products are for

    provisioning_instructions
    string <= 3500 characters

    Any provisioning instructions that have been provided with this order

    part_ship
    boolean
    Default: true

    If set to true, the order can be part-shipped. If false, the order will only be shipped as a complete unit.

    Array of objects (OrderLineItem)

    An array of line items

    name
    string

    The name of this order, used primarily for naming baskets

    payment_type
    string
    Enum: "ON_ACCOUNT" "FINANCE"

    Determines if the order is paid on account or finance

    object (OrderFinance)

    Responses

    Request samples

    Content type
    application/json
    {
    • "purchase_order_number": "PO5678",
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ]
    }

    Get basket by ID

    Returns a basket specified by ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ]
    }

    Modify basket by ID

    Modifies the basket

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer
    Request Body schema: application/json
    purchase_order_number
    string

    The user-supplied purchase order identifier

    object (Address)

    An address in Hub represents a physical location. It is used for shipping and for Dovetail sites.

    shipping_type
    integer

    The ID of the Shipping Type of this order

    ship_instructions
    string <= 3500 characters

    Any shipping instructions that have been provided with this order

    end_user
    string

    The End User that this order is for, or zoom products are for

    provisioning_instructions
    string <= 3500 characters

    Any provisioning instructions that have been provided with this order

    part_ship
    boolean
    Default: true

    If set to true, the order can be part-shipped. If false, the order will only be shipped as a complete unit.

    Array of objects (OrderLineItem)

    An array of line items

    name
    string

    The name of this order, used primarily for naming baskets

    payment_type
    string
    Enum: "ON_ACCOUNT" "FINANCE"

    Determines if the order is paid on account or finance

    object (OrderFinance)

    Responses

    Request samples

    Content type
    application/json
    {
    • "purchase_order_number": "PO5678",
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ]
    }

    Delete basket by ID

    Deletes basket by ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Checkout basket

    Submits basket to place order. Effectively transforms basket into an order object. The ID of the order will be the same as that of the basket.

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ]
    }

    Apply for finance

    Submits basket to finance for decision. Does not place order

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Response samples

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

    Add line item to basket

    Add a new line item to an existing basket

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer
    Request Body schema: application/json
    product
    integer

    The ID of the product that this line item represents

    product_code
    string

    When creating a line item, the SKU can be provided instead of the ID. If both product_code and product are supplied, product will take precedence.

    quantity
    integer

    The number of product this line item represents

    prov_product
    integer

    The ID of a related provisioning product that should be purchased and applied to this item

    prov_product_code
    string

    When creating a line item, the SKU can be provided instead of the ID. If both prov_product_code and prov_product are supplied, prov_product will take precedence.

    prov_organisation
    integer

    If the provisioning product is a Dovetail product (as indicated by the dovetail flag on the product relation), this can be set to the ID of the organisation that the device should be added to when the order has been shipped

    prov_group
    integer

    If the provisioning product is a Dovetail product (as indicated by the dovetail flag on the product relation), this can be set to the ID of the Dovetail group that the device should be added to when the order has been shipped

    prov_site
    integer

    If the provisioning product is a Dovetail product (as indicated by the dovetail flag on the product relation), this can be set to the ID of the Dovetail site that the device should be added to when the order has been shipped

    maintenance_product
    integer

    The ID of a related provisioning product that should be purchased and applied to this item

    maintenance_product_code
    string

    When creating a line item, the SKU can be provided instead of the ID. If both maintenance_product_code and maintenance_product are supplied, maintenance_product will take precedence

    selected_rate_plan
    integer

    When adding a product with rate plans, this selects the ID of the rate plan that should be purchased

    object (DropboxOrder)

    The Dropbox Order object is attached to an Order Line Item to provide the additional parameters for the created Dropbox team

    object (AcronisOrder)

    The Acronis Order object is attached to Order Line Item to provide the additional parameters for the created Acronis tenant

    object (ZoomOrder)

    The ZoomOrder object is attached to Order Line Item to provide the additional parameters for Zoom subscription purchases

    markup
    number

    percentage value of margin, is required if order has a finance object and finance.target is 'CUSTOMER'

    discount
    number

    percentage value of discount, which is applied to line item subtotal. Can only be applied from a quote

    Responses

    Request samples

    Content type
    application/json
    {
    • "product": 555,
    • "product_code": "123-4567-9101",
    • "quantity": 10,
    • "prov_product": 7,
    • "prov_product_code": 222,
    • "prov_organisation": 5,
    • "prov_group": 6,
    • "prov_site": 7,
    • "maintenance_product": 333,
    • "maintenance_product_code": 333,
    • "selected_rate_plan": 5,
    • "dropbox_order": {
      },
    • "acronis_order": {
      },
    • "zoom_order": {
      },
    • "markup": 0.5,
    • "discount": 0.5
    }

    Response samples

    Content type
    application/json
    {
    • "id": 1,
    • "order": 7745,
    • "product": 555,
    • "name": "A New Toaster",
    • "quantity": 10,
    • "price": 123.99,
    • "original_price": 200,
    • "prov_product": 7,
    • "prov_product_name": "Advanced Provisioning",
    • "prov_product_price": 1.99,
    • "prov_organisation": 5,
    • "prov_group": 6,
    • "prov_site": 7,
    • "maintenance_product": 333,
    • "maintenance_product_name": "24x7 Cover",
    • "maintenance_product_price": 2.99,
    • "sub_total_for_item": 1289.7,
    • "selected_rate_plan": 5,
    • "rate_plan_details": {
      },
    • "dropbox_order": {
      },
    • "acronis_order": {
      },
    • "zoom_order": {
      },
    • "markup": 0.5,
    • "discount": 0.5
    }

    Orders

    Orders are orders that have been sent into the Hub system. At this point they are immutable.

    Get orders

    Returns an optionally filtered and paginated list

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    status
    Array of strings
    Items Enum: "CREATED" "PROCESSING" "ACCEPTED" "PART_SHIPPED" "SHIPPED" "COMPLETE" "ATTENTION_REQUIRED" "FAILED" "PENDING_AUTHORISATION" "CANCELLED"
    Example: status=SHIPPED

    Filter by a list of statuses

    payment_type
    Array of strings
    Items Enum: "ON_ACCOUNT" "FINANCE"
    Example: payment_type=FINANCE

    Filter orders list by payment type

    text
    string
    Example: text=PO123456

    Filter by Hub Reference, Supplier Reference and Purchase order

    organisation
    Array of integers
    Example: organisation=1

    Filter by an array of organisation IDs

    start_date
    string <date>
    Example:

    Filter for orders created on or after this date

    end_date
    string <date>
    Example:

    Filter for orders created on or before this date

    value_from
    number
    Example: value_from=100

    Filter for orders with a total cost equal to or greater than this parameter

    value_to
    number
    Example: value_to=999.99

    Filter for orders with a total cost equal to or less than this parameter

    sort_by
    Array of strings
    Default: "-date"
    Items Enum: "-date" "-total" "+date" "+total"
    Example: sort_by=+date

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create order

    Creates a new order and immediately submits it.

    Authorizations:
    OAuth2
    Request Body schema: application/json
    purchase_order_number
    string

    The user-supplied purchase order identifier

    object (Address)

    An address in Hub represents a physical location. It is used for shipping and for Dovetail sites.

    shipping_type
    integer

    The ID of the Shipping Type of this order

    ship_instructions
    string <= 3500 characters

    Any shipping instructions that have been provided with this order

    end_user
    string

    The End User that this order is for, or zoom products are for

    provisioning_instructions
    string <= 3500 characters

    Any provisioning instructions that have been provided with this order

    part_ship
    boolean
    Default: true

    If set to true, the order can be part-shipped. If false, the order will only be shipped as a complete unit.

    Array of objects (OrderLineItem)

    An array of line items

    name
    string

    The name of this order, used primarily for naming baskets

    payment_type
    string
    Enum: "ON_ACCOUNT" "FINANCE"

    Determines if the order is paid on account or finance

    object (OrderFinance)

    Responses

    Request samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "purchase_order_number": "PO5678",
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "order_type": "SALES_ORDER"
    }

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Modify order by ID

    Modifies the Order

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer
    Request Body schema: application/json
    linked_supplier_refs
    Array of strings

    An array on linked SO refs, in string form

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Preview change order

    Previews a change order to a subscription and returns JSON obcject of costs associated.

    Authorizations:
    OAuth2
    Request Body schema: application/json
    purchase_order_number
    string

    The user-supplied purchase order identifier

    subscription
    integer

    The ID of the subscription this order is changing

    Array of objects (ChangeOrderLineItem)

    An array of line items

    Responses

    Request samples

    Content type
    application/json
    {
    • "purchase_order_number": "PO5678",
    • "subscription": 10,
    • "line_items": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "subscription_delta": 1,
    • "subscription_new": 5,
    • "tcv_delta": 399.99,
    • "tcv_new": 699.99,
    • "rc_delta": 39.99,
    • "rc_new": 69.99
    }

    Get order by ID

    Gets a given order by ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of order

    Responses

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Cancel order

    Cancels an order if it's in an cancellable state. Only orders that are in a PROCESSING state can be cancelled. Once they have been ACCEPTED or beyond you must contact your account manager to cancel the order.

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of order

    Responses

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Approve order

    Approves an order that's currently awaiting authorisation

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of order

    Responses

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Deny order

    Denies the specified order

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of order

    Responses

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Resubmit order

    Resubmits an order that is in an ATTENTION_REQUIRED state

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    Response samples

    Content type
    application/json
    Example
    SALES_ORDER
    SALES_ORDER
    CHANGE_ORDER
    {
    • "id": 1,
    • "external_id": 77272,
    • "purchase_order_number": "PO5678",
    • "supplier_ref": "SO1234567",
    • "linked_supplier_refs": [
      ],
    • "organisation": 10,
    • "date": "2020-01-30T10:30:00",
    • "status": "PROCESSING",
    • "parent_id": 10,
    • "shipping_address": {
      },
    • "shipping_type": 1,
    • "ship_instructions": "Please leave with security",
    • "ship_cost": 12.99,
    • "ship_final": true,
    • "discount": 1.99,
    • "end_user": "Bob's Customer",
    • "provisioning_instructions": "Please ensure firmware 1.2.3 is installed",
    • "manual_authorisation": true,
    • "total": 399.99,
    • "part_ship": true,
    • "line_items": [
      ],
    • "name": "Order for Bob's new customer",
    • "units": [
      ],
    • "attention_required": "The customer has exceeded their credit limit",
    • "payment_type": "ON_ACCOUNT",
    • "finance": {
      },
    • "shipments": [
      ],
    • "order_type": "SALES_ORDER"
    }

    Export orders as CSV

    Returns a file containing a list of orders in CSV format

    Authorizations:
    OAuth2
    Request Body schema: application/json
    Array ()
    integer

    Order ID to export

    Responses

    Request samples

    Content type
    application/json
    [
    • 1,
    • 4,
    • 5,
    • 6
    ]

    Subscriptions

    Subscriptions represent ongoing subscription services and costs.

    Get subscriptions

    Gets an optionally filtered list of subscriptions

    Authorizations:
    OAuth2
    query Parameters
    name
    string
    Example: name=Test

    Filter by name of subscription

    organisation
    Array of integers
    Example: organisation=1

    Filter by list of organisation IDs

    status
    Array of strings
    Items Enum: "ACTIVE" "PENDING" "EXPIRED"
    Example: status=ACTIVE

    Filter by list of statuses

    vendor
    Array of strings
    Items Enum: "ACRONIS" "DROPBOX"
    Example: vendor=DROPBOX

    Filter by list of vendors

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get subscription by ID

    Retrieves a subscription by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the subscription

    Responses

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Update subscription by ID

    Used to update a subscription by its ID. This is used for administrative tasks like enabling and disabling auto renew, but not modifying the subscription itself

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the subscription

    Request Body schema: application/json
    auto_renewal_flag
    boolean

    If true, this subscription will be automatically renewed on the end_date

    pending_change
    boolean

    If there are changes pending for this subscription the boolean will be true

    total_contract_value
    number

    The total contracted amount of this subscription

    Responses

    Request samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "total_contract_value": 400.5,
    • "type": "DROPBOX"
    }

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Activate the subscription

    activates a pending subscription

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of subscription

    Request Body schema: application/json
    service_activation_date
    date

    The date of the service activation

    Responses

    Request samples

    Content type
    application/json
    {
    • "service_activation_date": "2021-01-01T00:00:00.000Z"
    }

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Cancel the subscription

    Cancels a pending subscription

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of subscription

    Responses

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Activate pending changes on the subscription

    activates changes on a subscription

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of subscription

    Request Body schema: application/json
    activation_date
    date

    The date of the activation of changes

    Responses

    Request samples

    Content type
    application/json
    {
    • "activation_date": "2021-01-01T00:00:00.000Z"
    }

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Cancel pending changes on the subscription

    Cancels pending changes on a subscription

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of subscription

    Responses

    Response samples

    Content type
    application/json
    Example
    DROPBOX
    DROPBOX
    ACRONIS
    ZOOM
    {
    • "team_id": "5729290",
    • "admin_email": "admin@test.com",
    • "subscriptions": 12,
    • "id": 1,
    • "name": "Bob's Widgets",
    • "organisation": 1,
    • "order": 5,
    • "type": "DROPBOX",
    • "start_date": "2020-05-14",
    • "service_activation_date": "2020-05-14",
    • "end_date": "2021-05-14",
    • "auto_renewal_flag": true,
    • "pending_change": true,
    • "source_id": "A-S0000000123",
    • "status": "ACTIVE",
    • "billing_frequency": "MONTHLY",
    • "total_contract_value": 400.5,
    • "order_history": [
      ],
    • "associated_subscriptions": [
      ],
    • "products": [
      ]
    }

    Invoices

    Invoices show the invoices that have been sent to a given company.

    Get invoices

    Gets a list of invoices and credit notes

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    text
    string
    Example: text=INV123456

    Filter by invoice reference or purchase order number

    organisation
    Array of integers
    Example: organisation=1

    Filter by a list of organisation IDs

    status
    Array of strings
    Items Enum: "open" "paid_in_full" "pending_approval" "rejected" "voided"
    Example: status=open

    Filter by a list of statuses

    days_overdue
    Array of strings
    Items Enum: "0" "31-60" "61-90" "90+"
    Example: days_overdue=61-90

    Filter by a range of days overdue

    start_date
    string <date>
    Example:

    Filter on or after this date

    end_date
    string <date>
    Example:

    Filter before or on this date

    value_from
    number
    Example: value_from=1000

    Filter for invoice with a total greater than or equal to this parameter

    value_to
    number
    Example: value_to=5000

    Filter for invoice with a total less than or equal to this parameter

    type
    Array of strings
    Items Enum: "invoice" "credit_note"
    Example: type=invoice

    Filter by a list of types

    sort_by
    Array of strings
    Default: "-date"
    Items Enum: "-source_id" "+source_id" "-status" "+status" "-date" "+date" "-purchase_order" "+purchase_order" "-total" "+total" "-days_overdue" "+days_overdue"
    Example: sort_by=+date

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Vendors

    Vendors are used to group products under their respective vendors for better categorisation of products.

    Get vendors

    Gets the list of vendors used by Hub. Each product can have a single vendor, which can be used to filter down the result set of products.

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    []

    Shipping

    Shipping types and country codes are important parts of the shipping process and are used to determine how and where an order is delivered.

    Get shipping types

    Shipping types are used to select how an order should be delivered

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get country codes

    Country codes are the objects used for selecting destination country when shipping

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Groups

    Groups are used to group Dovetail devices into logical groups.

    Get groups

    Gets a list of Dovetail groups

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Sites

    Sites are an optional object used for the categorisation and grouping of Dovetail devices. They repesent physical locations.

    Get sites

    Gets a list of Dovetail sites

    Authorizations:
    OAuth2

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Feeds

    Feeds are used to set up delivery of daily price and stock feeds from Hub.

    Get feeds

    Get list of feed configurations

    Authorizations:
    OAuth2
    query Parameters
    name
    string
    Example: name=Stock feed

    Filter by name of feed

    organisation
    Array of integers
    Example: organisation=1

    Filter by organisation IDs

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Create a new feed configuration

    Create a new feed configuration

    Authorizations:
    OAuth2
    Request Body schema: application/json
    delivery_email
    string <email>

    The email address the feed should be delivered to

    show_headers
    boolean

    Determines whether csv file contains a header row or not

    delimiter
    string
    Enum: "COMMA" "SEMI_COLON"

    Specifies whether feed file should be delimited by comma ',' or semicolon ';' characters

    escape_method
    string
    Enum: "ESCAPED" "QUOTED" "STRIPPED"

    Describes how to handle delimiter characters occuring in data ESCAPED: 123,Delimiters\, should be escaped,456 QUOTED: 123,"Delimiters, should be quoted",456 STRIPPED: 123,Delimiters should be stripped,456

    organisation
    required
    integer

    The ID of the organisation to which this configuration belongs

    name
    required
    string

    The name of the feed

    active
    required
    boolean
    Default: true

    Whether or not the feed should be generated

    timeslot
    required
    integer

    Offset (in minutes UTC) in 30 minute intervals from midnight (00:00), a request will be rejected if value is not a valid interval

    show_empty_stock
    boolean
    Default: false

    If enabled, empty stock of physical items will be printed as a 0, otherwise they will be displayed as an empty field

    columns
    required
    Array of strings
    Items Enum: "stock" "mpn" "price" "rrp" "vendor" "name" "ean"

    The list of columns that should be in the generated feed

    delivery_method
    required
    string

    The delivery method of this feed

    EMAIL
    EMAIL
    FTP
    SITC

    Responses

    Request samples

    Content type
    application/json
    Example
    EMAIL
    EMAIL
    FTP
    SITC
    {
    • "delivery_email": "user@example.com",
    • "show_headers": true,
    • "delimiter": "COMMA",
    • "escape_method": "ESCAPED",
    • "organisation": 1,
    • "name": "Price feed",
    • "active": true,
    • "timeslot": 90,
    • "show_empty_stock": true,
    • "columns": [
      ],
    • "delivery_method": "EMAIL"
    }

    Response samples

    Content type
    application/json
    Example
    EMAIL
    EMAIL
    FTP
    SITC
    {
    • "delivery_email": "user@example.com",
    • "show_headers": true,
    • "delimiter": "COMMA",
    • "escape_method": "ESCAPED",
    • "id": 1,
    • "organisation": 1,
    • "name": "Price feed",
    • "active": true,
    • "timeslot": 90,
    • "show_empty_stock": true,
    • "columns": [
      ],
    • "delivery_method": "EMAIL",
    • "last_upload": "2020-06-18T00:20:00.000000"
    }

    Get feed by ID

    Get a single feed configuration

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the feed configuration

    Responses

    Response samples

    Content type
    application/json
    Example
    EMAIL
    EMAIL
    FTP
    SITC
    {
    • "delivery_email": "user@example.com",
    • "show_headers": true,
    • "delimiter": "COMMA",
    • "escape_method": "ESCAPED",
    • "id": 1,
    • "organisation": 1,
    • "name": "Price feed",
    • "active": true,
    • "timeslot": 90,
    • "show_empty_stock": true,
    • "columns": [
      ],
    • "delivery_method": "EMAIL",
    • "last_upload": "2020-06-18T00:20:00.000000"
    }

    Update feed by ID

    Modify the feed configuration

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the feed configuration

    Request Body schema: application/json
    delivery_email
    string <email>

    The email address the feed should be delivered to

    show_headers
    boolean

    Determines whether csv file contains a header row or not

    delimiter
    string
    Enum: "COMMA" "SEMI_COLON"

    Specifies whether feed file should be delimited by comma ',' or semicolon ';' characters

    escape_method
    string
    Enum: "ESCAPED" "QUOTED" "STRIPPED"

    Describes how to handle delimiter characters occuring in data ESCAPED: 123,Delimiters\, should be escaped,456 QUOTED: 123,"Delimiters, should be quoted",456 STRIPPED: 123,Delimiters should be stripped,456

    organisation
    required
    integer

    The ID of the organisation to which this configuration belongs

    name
    required
    string

    The name of the feed

    active
    required
    boolean
    Default: true

    Whether or not the feed should be generated

    timeslot
    required
    integer

    Offset (in minutes UTC) in 30 minute intervals from midnight (00:00), a request will be rejected if value is not a valid interval

    show_empty_stock
    boolean
    Default: false

    If enabled, empty stock of physical items will be printed as a 0, otherwise they will be displayed as an empty field

    columns
    required
    Array of strings
    Items Enum: "stock" "mpn" "price" "rrp" "vendor" "name" "ean"

    The list of columns that should be in the generated feed

    delivery_method
    required
    string

    The delivery method of this feed

    EMAIL
    EMAIL
    FTP
    SITC

    Responses

    Request samples

    Content type
    application/json
    Example
    EMAIL
    EMAIL
    FTP
    SITC
    {
    • "delivery_email": "user@example.com",
    • "show_headers": true,
    • "delimiter": "COMMA",
    • "escape_method": "ESCAPED",
    • "organisation": 1,
    • "name": "Price feed",
    • "active": true,
    • "timeslot": 90,
    • "show_empty_stock": true,
    • "columns": [
      ],
    • "delivery_method": "EMAIL"
    }

    Response samples

    Content type
    application/json
    Example
    EMAIL
    EMAIL
    FTP
    SITC
    {
    • "delivery_email": "user@example.com",
    • "show_headers": true,
    • "delimiter": "COMMA",
    • "escape_method": "ESCAPED",
    • "id": 1,
    • "organisation": 1,
    • "name": "Price feed",
    • "active": true,
    • "timeslot": 90,
    • "show_empty_stock": true,
    • "columns": [
      ],
    • "delivery_method": "EMAIL",
    • "last_upload": "2020-06-18T00:20:00.000000"
    }

    Delete feed by ID

    Delete an existing feed configuration

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the feed configuration

    Responses

    Test feed

    Schedules the feed for run in the next timeslot

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the feed configuration to test

    Responses

    Download feed

    Downloads the last generated feed file

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of the feed configuration to download

    Responses

    Filtering

    Where a list API allows filtering, the rules between different parameters are applied as ANDs, while a parameter with multiple values are applied as ORs.

    For example, if a filter query string was organisation=5&organisation=10&type=invoice this would look for invoices only with an organisation of 5 or 6.

    Pagination

    Pagination is achieved with two parameters that are applied consistently across the API.

    • per_page defines the number of results desired in a given page.
    • page starts at 1 and defines the page of results you wish to view

    For example, if per_page is set to 24 and page is set to 2 you will receive results 25-48.

    Results will include the X-Total-Count and X-Total-Pages headers that define the total number of results, and the total number of pages.