Quantivate API Documentation

Quantivate API

1.Introduction

The Quantivate API allows you to gather significant actionable data in real time by exposing basic functions in a JSON-RPC style allowing you to interact with Quantivate data. The following documentation includes pertinent technical details in relation to the API including: authentication, call structure, and various methods available.

2.Authentication

Get started by requesting an access token from Quantivate Support (support@quantivate.com).  We will email you a temporary (48 hour) link to retrieve your permanent JSON Web Token (JWT). The permanent JWT you get will need to be included in all of your requests, either within an Authorization header, or as a query parameter named “jwt”. It is recommended that you use the “Authorization: Bearer” header option:

Authorization: Bearer <token>

3.Rate Limiting

Each request will return X-RateLimit headers showing the Limit, Remaining Calls, and the time at which the Remaining Calls will reset to the Limit (Reset).

  1. X-RateLimit-Limit – The maximum number of requests that the user is allowed to make in the time window.
  2. X-RateLimit-Remaining – The number of requests remaining in the current rate limit window.
  3. X-RateLimit-Reset – The time at which the current rate limit window resets in UTC epoch seconds.

There are three rate limit categories enforced on each request to the Quantivate API (IP, Token, and License):

  • For any IP, you will get 10 calls per minute, beginning at the first call.  This will reset on the first request after the minute has passed.
  • For your JWT, you will get 15 calls per minute, beginning at the first call.  This will reset on the first request after the minute has passed.
  • For the license, you will get a number of calls (based on your MSA) for the month.  This will reset on first request of each new month.

The following are example response headers for each category:

  1. Rate limit per IP
    1. X-RateLimitIP-Limit: 10
    2. X-RateLimitIP-Remaining: 5
    3. X-RateLimitIP-Reset: 1525733404
  2. Rate limit per Access Token
    1. X-RateLimitJWT-Limit: 15
    2. X-RateLimitJWT-Remaining: 5
    3. X-RateLimitJWT-Reset: 1525733404
  3. Rate limit per client
    1. X-RateLimitLicense-Limit: 100
    2. X-RateLimitLicense-Remaining: 34
  4. X-RateLimitLicense-Reset: 1527894471

When an application exceeds any of the rate limits, the API will return a HTTP 429 “Too Many Requests” response code, and the following errors will be returned in the response body:

{"error":{"message":"Too many requests for this IP","code":429}}
{"error":{"message":"Too many requests for this JWT","code":429}}
{"error":{"message":"Licensed API calls for the month used up","code":429}}

4.API Call Structure

API Call Structure

To make an API call, you will need to supply a valid JWT (for authorization) and a JSON-RPC. The JSON-RPC must include at least these two properties: “method” and “params”.

For any method that requires resourceTypeName as a parameter, that resource type MUST have an attribute that is set to unique, default, and required in the Quantivate platform.

See the following examples for a basic API call.  For other methods, you will replace the “method” and “params” properties with the desired method name and respective parameters.

Example URL:
https://api.quantivate.com/
?jwt=<token>&rpc=
{"method":"getResource","params":{"resourceTypeName":"Vendor","resourceName":"AAA"}}
Example cURL:
curl --request GET \
     --header "Authorization: Bearer <token>" \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"method\": \"getResource\", 
    \"params\": 
    {                
        \"resourceTypeName\": \"Vendor\",
        \"resourceName\": \"AAA\"
    }
}" \
'https://api.quantivate.com'

 

Example Error Response:

{
    "error":  
    {                
        "message": "No resource of type 'Vendor' exists or resource is in trash bin with name: 'AAA'",
        "code": 5
    }
}

 

 


4.1.Method Parameters

Parameters

Each method accepts parameters that are required. Below is a list of all possible parameter types that can be placed in the JSON object nested under the “params” property. A given parameter may be used by more than one method. See section titled “Methods” for a list of parameters required for each specific JSON-RPC method.

Parameter Description Errors
resourceTypeName Name of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
resourceName Name of a resource for a resource type; this must be unique across the resource type
  • No resource of type ‘<Resource Type Name>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>
attributes Key value pairs of attribute names in a resource type and accepted data for the attribute type (see table below)
  • Parameter ‘attributes’ must be an object of the form { ‘attribute name’:’value’ }
  • One or more required attributes are missing or blank: […]
  • Attribute ‘<attribute name>’ does not exist in ‘<Resource Type Name>’ resource type or is a calculated value
  • One or more attributes don’t exist in type ‘<Resource Type Name>’ or cannot be updated in this way
  • Invalid value ‘<value>’ for attribute ‘<attribute name>’
  • Attribute ‘<attribute name>’ is of type ‘<attribute type>’ or cannot be created or updated in this way
reportName Unique name of report
  • Missing ‘<reportName>’ parameter
  • More than one report exists with name: ‘<reportName’>
  • No report exists with name: ‘<reportName>’ OR it’s in the trash bin
  • Report is not of type ‘resource’
  • Unsupported report type
  • Unsupported report display type
groupName Unique name of group
  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
employeeName Unique name of employee formatted like “Last Name, First Name” as it appears in Quantivate
  • More than one employee exists with name: <employeeName>
  • Employee does not exist: ‘<employeeName>’
role A valid group role; either “Group Viewer” or “Group Modifier”
  • Invalid group role: ‘<groupRole>’. Must be one of: ‘Group Viewer’, ‘Group Modifier’
upstreamResourceTypeName Name of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
upstreamResourceName Name of a resource for a resource type; this must be unique across the resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>
downstreamResourceTypeName Name of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
downstreamResourceName Name of a resource for a resource type; this must be unique across the resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

 

tableName Name of a table attribute within the resource type
  • Table does not exist in <resourceTypeName>: ‘<tableName>’
tableAttributes Key value pairs of attribute names in the table and accepted data for the attribute type (see table below)
  • <Attribute Name> does not exist in <Table Name>
  • Same errors as the resource ‘attributes’ parameter

Parameter “attributes” and “tableAttributes”

Key value pairs of attribute names in a resource type and accepted data for the attribute type:

Attribute Type Accepts
Date Must be a date formatted as “MM/DD/YYYY”
Employee Unique name of employee formatted like “Last Name, First Name” as it appears in Quantivate
Select Must be the text of the select option as set in Quantivate
Select Multiple Must be the text of the select options as set in Quantivate, in a JSON array. E.g.: [“Yes”,”No”,”Maybe”]
Checkbox For non-customized checkboxes, either “on” or blank. For customized checkboxes, either the value for checked or unchecked as set in Quantivate
Number Value must be numeric
Currency Value must be numeric, or formatted like “1,000.00”. It must also be between these values (-9999999999999.99 and 9999999999999.99)

5.Methods

The following section includes a description and other details on the various methods that can be called using the Quantivate API to interact with your data.

5.1.getResource

Use this method to retrieve attribute values for a given resource

Parameters:

  • resourceTypeName (string)
  • resourceName
  {
      "method": "getResource", 
      "params": 
      {                
          "resourceTypeName": "Vendor",
          "resourceName": "Quantivate"
      }
  }

Returns:

JSON object with resource information or failure message.
Success:

{
   "result":  
   {                
       "Vendor Name": "Quantivate",
       "Zip": "98072",
       "State": "WA",
       ...
   }
}

Example Error:

{
      "error":  
      {
          "message": "No resource of type 'Vendor' exists or resource is in trash bin with name: 'AAA'",
          "code": "7"
      }
}

 

Errors:

  • Missing required parameter
  • Invalid required parameter
  • Resource type does not exist
  • No required unique default attribute found for resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

5.2.addResource

Use this method to create a resource with the given attributes. The name of the resource will be set to the value provided for the attribute that is set to default in the Quantivate platform

Parameters:

  • resourceTypeName
  • attributes

Request Body:

{
    "method": "addResource",
    "params": 
    {
        "resourceTypeName": "Vendor",
        "attributes": {
            "Vendor Name": "Dunk n Donuts",
            "State": "WA",
            "Zip Code": 98072,
            "Associated Employee": "Smith, John A"
        }
    }
}

Returns:

  • JSON object with resource information on Success, or error message

Errors:

  • Invalid Resource Type
  • Fail constraints: Unique, Required
  • Fail Attribute format requirements
  • Date – bad format
  • Employee – employee doesn’t exist
  • Select – option doesn’t exist
  • Select Multiple – option doesn’t exist
  • Checkbox – invalid value
  • Number – not a number
  • Currency – not a valid currency
  • Attribute does not exist
  • Attribute type cannot be updated via this method

5.3.updateResource

Use this method to update a resource and its attributes.

Parameters:

  • resourceTypeName (string)
  • resourceName
  • attributes and values
{  
    "method":"updateResource",
    "params": { 
        "resourceTypeName":"Vendor", 
        "resourceName":"AAA Washington",
        "attributes": {
            "Vendor Name": "Donuts",  
            "State":"WA",
            "Zip Code":98072
        }
    }
}

Returns:

  • JSON object with resource information on Success, or error message

Errors:

  • Invalid Resource Type
  • Fail constraints: Unique, Required
  • Fail Attribute format requirements
  • Date – bad format
  • Employee – employee doesn’t exist
  • Select – option doesn’t exist
  • Select Multiple – option doesn’t exist
  • Checkbox – invalid value
  • Number – not a number
  • Currency – not a valid currency
  • Attribute does not exist
  • Attribute type cannot be updated via this method

5.4.trashResource

Use this method to put a resource into the trash bin

Parameters:

  • resourceTypeName
  • resourceName

Request Body:

{
    "method": "trashResource",
    "params": {
        "resourceName": "Quantivate",
        "resourceTypeName": "Vendor"
    }
}

Response:

{
    "result": "Success"
}

 

 

Errors:

  • Resource type does not exist
  • No required unique default attribute found for resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

5.5.runResourceReport

Use this method to retrieve data from a resource report in Quantivate

Parameters:

  • reportName

Request Body:

{
    "method": "runResourceReport",
    "params": {
        "reportName": "All Vendors"
    }
}

Response:

{
    "columns": ["Vendor Name", "Vendor Description",...],
    "data": [
        ["Quantivate", "The best vendor ever",...],
        ["Dunk'n Donuts", "The second best vendor",...],
        ...
     ]
}

 

Errors:

  • Missing ‘<reportName>’ parameter
  • More than one report exists with name: ‘<reportName’>
  • No report exists with name: ‘<reportName>’ OR it’s in the trash bin
  • Report is not of type ‘resource’
  • Unsupported report type
  • Unsupported report display type

5.6.addGroupOwnership

Gives ownership of a resource to the given group

Parameters:

  • groupName
  • resourceTypeName
  • resourceName

Request Body:

{
    "method": "addGroupOwnership",
    "params":
    {
        "groupName": "Accounts Payable",
        "resourceTypeName": "Vendor",
        "resourceName": "Quantivate"
    }
}

Response:

{
    "result": "Success"
}

Errors:

  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
  • Resource type does not exist
  • No required unique default attribute found for resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

5.7.removeGroupOwnership

Revokes ownership of a resource from a group

Parameters:

  • groupName
  • resourceTypeName
  • resourceName

Request Body:

{
    "method": "removeGroupOwnership",
    "params":
    {
        "groupName": "Accounts Payable",
        "resourceTypeName": "Vendor",
        "resourceName": "Quantivate"
    }
}

Response:

{
    "result": "Success"
}

 

 

Errors:

  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
  • Resource type does not exist
  • No required unique default attribute found for resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

5.8.setGroupMembership

Assigns an employee to a group with the given role

Parameters:

  • groupName
  • employeeName
  • role (“Group Viewer” or “Group Modifier”)

Request Body:

{
    "method": "setGroupMembership",
    "params":
    {
        "groupName": "Accounts Payable",
        "employeeName": "Smith, John A",
        "role": "Group Viewer"
    }
}

Response:

{
    "result": "Success"
}

 

 

Errors:

  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
  • More than one employee exists with name: ‘<employeeName>’
  • Employee does not exist: ‘<employeeName>’
  • Invalid group role: ‘<groupRole>’.  Must be one of: ‘Group Viewer’, ‘Group Modifier’

5.9.removeGroupMembership

Revokes membership into a group from the given employee

Parameters:

  • groupName
  • employeeName

Request Body:

{
    "method": "removeGroupMembership",
    "params":
    {
        "groupName": "Accounts Payable",
        "employeeName": "Smith, John A",
    }
}

Response:

{
    "result": "Success"
}

 

 

Errors:

  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
  • More than one employee exists with name: <employeeName>
  • Employee does not exist: ‘<employeeName>’

5.10.linkResources

Links an upstream (dependency) resource to a downstream (customer) resource

Parameters:

  • upstreamResourceTypeName
  • upstreamResourceName
  • downstreamResourceTypeName
  • downstreamResourceName

Request Body:

{
    "method": "linkResources",
    "params":
    {
        "upstreamResourceTypeName": "Vendor",
        "upstreamResourceName": "Quantivate",
        "downstreamResourceTypeName": "Vendor",
        "downstreamResourceName": "15 Year Contract"
    }
}

Response:

{
    "result": "Success"
}

 

 

 

Errors:

  • Resource type does not exist
  • No required unique default attribute found for resource type
  • No resource of type ‘<Resource Type>’ exists or resource is in trash bin with name: ‘<Resource Name>’
  • More than one <Resource Type Name> exists with name: <Resource Name>

5.11.addTableRow

Adds a row to a table in the given resource

Parameters:

  • resourceTypeName
  • resourceName
  • tableName
  • tableAttributes and values

Request Body:

{
    "method": "addTableRow",
    "params": {
        "resourceTypeName": "Vendor",
        "resourceName": "Quantivate",
        "tableName": "Spend items",
        "tableAttributes": {
            "Recipient": "Donuts R Us",
            "Date": "12/31/1999",
            "Amount": "98,072.00",
            "Purchaser": "Smith, John A"
        }
    }
}

Response:

{
    "result": "Success"
}

 

Errors:

  • Invalid Resource Type
  • Invalid Table Name
  • Fail constraints: Unique, Required
  • Fail Attribute format requirements
  • Date – bad format
  • Employee – employee doesn’t exist
  • Select – option doesn’t exist
  • Select Multiple – option doesn’t exist
  • Checkbox – invalid value
  • Number – not a number
  • Currency – not a valid currency
  • Attribute does not exist
  • Attribute type cannot be updated via this method

6.Error and Exception Handling

The table below provides a list of general errors or exceptions that can be returned by the API.

Errors and Codes
Error Description Code
Invalid Method An unsupported method was given in the JSON-RPC 1
Missing Request Parameter Missing either the “method” or “params” object in the JSON-RPC 2
Invalid Parameter Value An invalid parameter was found in the JSON-RPC 3
Missing Method Parameter A method call was attempted missing a required parameter 4
Unknown Resource Type An unknown “resourceTypeName” parameter was provided 5
No Unique Default For Resource Type A resource type is not configured to work with the API (needs a required, unique, default attribute) 6
Unknown Resource The provided resource name cannot be found in the resource type 7
Duplicate Resource Name A name provided for the “resourceName” parameter is not unique in the system 8
Invalid Employee An unknown employee name was provided 9
Duplicate Employee Name A name provided for an “employee” type attribute, or in the “employeeName” parameter is not unique in the system 10
Missing Required Attribute An “attributes” parameter is missing a required attribute for the resource type 11
Invalid Attribute Value An invalid attribute value was provided 12
Malformed Attributes Parameter An invalid “attributes” parameter was provided 13
Unsupported Attribute Type An attribute was provided that is not supported 14
Attribute Does Not Exist An attribute name provided in “attributes” does not exist 15
Invalid Date Invalidly formatted date was provided 16
Non Numeric Number A non numeric value was provided for a numeric attribute type 17
Conflicting Unique Value A table value provided in “attributes” must be unique across the resource type 18
Invalid Checkbox Option An invalid checkbox value was provided 19
Invalid Select Option An invalid option was provided for a select attribute type 20
Invalid Select Multiple Option An invalid option was provided for a select multiple attribute type 21
Invalid Url An invalid URL was provided for a hyperlink attribute type 22
Erroneous Attribute A unsupported attribute was provided 23
Table Does Not Exist An invalid “tableName” parameter was provided 24
Conflicting Unique Table Value A table value provided in “tableAttributes” must be unique across the table 25
Table Column Does Not Exist An invalid table column was provided in the “tableAttributes” parameter 26
Invalid Group Role An invalid group role was provided 27
Unknown Group An invalid “groupName” parameter was provided 28
Duplicate Group Name A name provided for the “groupName” parameter is not unique in the system 29
Empty Report Name You must supply a name for the report to run 30
Unknown Report Name No report exists with name: ” OR this report is not of type ‘resource’ OR it’s in the trash bin 31
Two Reports One Name More than one report exists with name: 32
Unsupported Report Type An unsupported report type was requested 33
Unsupported Report Display Type An unsupported report display type was requested 34
Invalid Currency An invalid currency value was provided 35
Unexpected Exception An unexpected error has occurred 99