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.

ParameterDescriptionErrors
resourceTypeNameName of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
resourceNameName 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>
attributesKey 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
reportNameUnique 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
groupNameUnique name of group
  • More than one group exists with name: ‘<groupName>’
  • No Group exists with name: ‘<groupName>’
employeeNameUnique 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>’
roleA valid group role; either “Group Viewer” or “Group Modifier”
  • Invalid group role: ‘<groupRole>’. Must be one of: ‘Group Viewer’, ‘Group Modifier’
upstreamResourceTypeNameName of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
upstreamResourceNameName 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>
downstreamResourceTypeNameName of a resource type
  • Resource type does not exist
  • No required unique default attribute found for resource type
downstreamResourceNameName 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>

 

tableNameName of a table attribute within the resource type
  • Table does not exist in <resourceTypeName>: ‘<tableName>’
tableAttributesKey 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 TypeAccepts
DateMust be a date formatted as “MM/DD/YYYY”
EmployeeUnique name of employee formatted like “Last Name, First Name” as it appears in Quantivate
SelectMust be the text of the select option as set in Quantivate
Select MultipleMust be the text of the select options as set in Quantivate, in a JSON array. E.g.: [“Yes”,”No”,”Maybe”]
CheckboxFor non-customized checkboxes, either “on” or blank. For customized checkboxes, either the value for checked or unchecked as set in Quantivate
NumberValue must be numeric
CurrencyValue 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
ErrorDescriptionCode
Invalid MethodAn unsupported method was given in the JSON-RPC1
Missing Request ParameterMissing either the “method” or “params” object in the JSON-RPC2
Invalid Parameter ValueAn invalid parameter was found in the JSON-RPC3
Missing Method ParameterA method call was attempted missing a required parameter4
Unknown Resource TypeAn unknown “resourceTypeName” parameter was provided5
No Unique Default For Resource TypeA resource type is not configured to work with the API (needs a required, unique, default attribute)6
Unknown ResourceThe provided resource name cannot be found in the resource type7
Duplicate Resource NameA name provided for the “resourceName” parameter is not unique in the system8
Invalid EmployeeAn unknown employee name was provided9
Duplicate Employee NameA name provided for an “employee” type attribute, or in the “employeeName” parameter is not unique in the system10
Missing Required AttributeAn “attributes” parameter is missing a required attribute for the resource type11
Invalid Attribute ValueAn invalid attribute value was provided12
Malformed Attributes ParameterAn invalid “attributes” parameter was provided13
Unsupported Attribute TypeAn attribute was provided that is not supported14
Attribute Does Not ExistAn attribute name provided in “attributes” does not exist15
Invalid DateInvalidly formatted date was provided16
Non Numeric NumberA non numeric value was provided for a numeric attribute type17
Conflicting Unique ValueA table value provided in “attributes” must be unique across the resource type18
Invalid Checkbox OptionAn invalid checkbox value was provided19
Invalid Select OptionAn invalid option was provided for a select attribute type20
Invalid Select Multiple OptionAn invalid option was provided for a select multiple attribute type21
Invalid UrlAn invalid URL was provided for a hyperlink attribute type22
Erroneous AttributeA unsupported attribute was provided23
Table Does Not ExistAn invalid “tableName” parameter was provided24
Conflicting Unique Table ValueA table value provided in “tableAttributes” must be unique across the table25
Table Column Does Not ExistAn invalid table column was provided in the “tableAttributes” parameter26
Invalid Group RoleAn invalid group role was provided27
Unknown GroupAn invalid “groupName” parameter was provided28
Duplicate Group NameA name provided for the “groupName” parameter is not unique in the system29
Empty Report NameYou must supply a name for the report to run30
Unknown Report NameNo report exists with name: ” OR this report is not of type ‘resource’ OR it’s in the trash bin31
Two Reports One NameMore than one report exists with name:32
Unsupported Report TypeAn unsupported report type was requested33
Unsupported Report Display TypeAn unsupported report display type was requested34
Invalid CurrencyAn invalid currency value was provided35
Unexpected ExceptionAn unexpected error has occurred99