Introduction

The Juniper Contract API consists of 3 APIs. The JSON representations for each API request and response are provided below. The JSON Key Details section provides details of each json key such as data type, data size, mandatory/optional and comments to help you learn about the APIs.

Note The synchronous response to an api request will always be a http response with code of 200 or 400. (Success or Client Error).

The response payload has four key attributes (viz. statusCode, status, message and an optional fault array) for the Client application to pay attention too.

  • A Success response (http code of 200) with the payload having statusCode of 200 indicates request has been processed successfully and no further action is required.
  • A Client Error response (http code of 400) will always have in the payload a statusCode of 400 AND a fault array with one or more errors.

Required headers in each API request sent

The following are the required headers to be sent in each Contract API call.

Headers Value
Authorization Required (string) for OIDC based Authorization is Bearer OIDC_ID_TOKEN and for OAuth2.0 based Authorization is Bearer ACCESS_TOKEN

Example

Bearer WQiOiJzMTBZa0hZNnRhVHgtWFNidWttV2ZkZW5Hb2x1Q2NlVkI3VWU1Z2JoTm5rIiwiYWxnIjoiUlMyNTYifQ.WIiOiIwMHVtYm84OHprZEJRVmxKTjBoNyIsIm5hbWUiOiJWZW5rYXQgQmVsbGFta29uZGEiLCJsb2NhbGUiOiJlbi1VUyIsInZlciI6MSwiaXNzIjoiaHR0cHM6Ly9qdW5pcGVyLXBvYy5va3RhcHJldmlldy5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiIwb2FmdHBqYXRrRmc5a3VuazBoNyIsImlhdCI6MTU3NDc4ODY5MSwiZXhwIjoxNTc0NzkyMjkxLCJqdGkiOiJJRC5VbFlibmVRVkxhekVpS0pXS2QwLUlERm96TV9sTGVoYzIwY1JFd2VGRUVBIiwiYW1yIjpbInB3ZCJdLCJpZHAiOiIwMG9mdGUxYXFjY1JrUTZmTTBoNyIsIm5vbmNlIjoicHNtZ1lWeFB6MlRIbUFmSTZlN0F5Q1NQc3o5TWtHaHciLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ2ZW5rYXRiQGp1bmlwZXIubmV0IiwiZ2l2ZW5fbmFtZSI6IlZlbmthdCIsImZhbWlseV9uYW1lIjoiQmVsbGFta29uZGEiLCJ6b25laW5mbyI6IkFtZXJpY2EvTG9zX0FuZ2VsZXMiLCJ1cGRhdGVkX2F0IjoxNTY0NjE1MzUxLCJhdXRoX3RpbWUiOjE1NzQ3ODg2OTB9.yq_Udq_h4JcEbSJJI9uRJD6PtESsnj9qAzd8R0D4nNechWUAeiCThGJCFGn--MSRM-fhek8IY9RrXltUiRqDBTthTxKQHWt-JIp4zGNBVep0IGVE64SjK8dvD84-M1D3n-ZPWKusvQGtqpJPbeQoSeNrJulA-tdWZLS6Q3ke_0uUiuK7iWHnHX2m_VqKz0sga_uQmYCMTI_FBsqTfFrpSwoZCCXSE4sB-m3lLGy4Ho8PZEmYqlB6fxGnzui08cuNhjgsJKPMyohXJ2hwQQwBYxfSGRXa7g-adPSGoBbvDqYiDS0ijCwzRRxS_k2vr-I5vVTAtNjewozIFV0Um4-Tdg
Accept application/json
Content-Type application/json

querycontracts

This API synchronously returns the details of Asset Ids matching the input criteria chosen.

The input criteria can only be ONE of the following

  • UTC DateTime window up to last 24-hours
  • Set of Sales Order Numbers [1…1000]
  • Set of Purchase Order Numbers [1…1000]
  • Set of Contract IDs [1…1000]

Optionally, with any of the above 4 criteria, the following can be passed in the request to further refine/limit the contract IDs’ returned.

  • contractStatus: [“Active”,”Expired”] AND/OR
  • contractStartDate [YYYY-MM-DD] AND/OR
  • contractEndDate [YYYY-MM-DD]

The response is contract IDs along with additional header details for each contract matching the input criteria.

{
  "queryContractsRequest": {
    "appID": "string",
    "requestDateTime": "string",
    "customerUniqueTransactionID": "string",
    "customerSourceID": "string",
    "contractsFromDateTime": "string",
    "contractsToDateTime": "string",
    "contractNumbers": [
      "string"
    ],
    "salesOrderNumbers": [
      "string"
    ],
    "purchaseOrderNumbers": [
      "string"
    ],
    "contractStatus": "string",
    "contractStartDate": "string",
    "contractEndDate": "string"
  }
}
HTTP status code - 200
{
  "queryContractsResponse": {
    "responseDateTime": "string",
    "customerUniqueTransactionID": "string",
    "customerSourceID": "string",
    "statusCode": "200",
    "status": "Success",
    "message": "Successfully processed the request",
    "data": {
      "invalidContractNumbers": [
        {
          "contractNumber": "String",
          "message": "String"
        }
      ],
      "invalidSalesOrderNumbers": [
        {
          "salesOrderNumber": "String",
          "message": "String"
        }
      ],
      "invalidPurchaseOrderNumbers": [
        {
          "purchaseOrderNumber": "String",
          "message": "String"
        }
      ],
      "contracts": [
        {
          "contractNumber": "number",
          "contractCreatedDate": "string",
          "contractLastModifiedDate": "string",
          "contractType": "string",
          "contractStatus": "string",
          "contractStartDate": "string",
          "contractEndDate": "string",
          "renewed": "boolean",
          "salesOrderNumber": "number",
          "purchaseOrderNumber": "string",
          "endCustomerId": "number",
          "endCustomerName": "string",
          "endCustomerAddressLine1": "string",
          "endCustomerCity": "string",
          "endCustomerStateRegionProvince": "string",
          "endCustomerPostalCode": "string",
          "endCustomerCountry": "string",
          "resellerId": "number",
          "resellerVarId": "string",
          "resellerName": "string",
          "resellerAddressLine1": "string",
          "resellerCity": "string",
          "resellerStateRegionProvince": "string",
          "resellerPostalCode": "string",
          "resellerCountry": "string",
          "distributorId": "number",
          "distributorName": "string",
          "distributorAddressLine1": "string",
          "distributorCity": "string",
          "distributorStateRegionProvince": "string",
          "distributorPostalCode": "string",
          "distributorCountry": "string",
          "juniperContactName": "string"
        },
        {
          "contractNumber": "number",
          "contractCreatedDate": "string",
          "contractLastModifiedDate": "string",
          "contractType": "string",
          "contractStatus": "string",
          "contractStartDate": "string",
          "contractEndDate": "string",
          "renewed": "boolean",
          "salesOrderNumber": "number",
          "purchaseOrderNumber": "string",
          "endCustomerId": "number",
          "endCustomerName": "string",
          "endCustomerAddressLine1": "string",
          "endCustomerCity": "string",
          "endCustomerStateRegionProvince": "string",
          "endCustomerPostalCode": "string",
          "endCustomerCountry": "string",
          "resellerId": "number",
          "resellerVarId": "string",
          "resellerName": "string",
          "resellerAddressLine1": "string",
          "resellerCity": "string",
          "resellerStateRegionProvince": "string",
          "resellerPostalCode": "string",
          "resellerCountry": "string",
          "distributorId": "number",
          "distributorName": "string",
          "distributorAddressLine1": "string",
          "distributorCity": "string",
          "distributorStateRegionProvince": "string",
          "distributorPostalCode": "string",
          "distributorCountry": "string",
          "juniperContactName": "string"
        }
      ]
    }
  }
}
HTTP status code - 400
{
  "queryContractsResponse": {
    "responseDateTime": "String",
    "customerUniqueTransactionID": "String",
    "customerSourceID": "String",
    "message": "Error in processing the request",
    "status": "Error",
    "statusCode": "400",
    "fault": [
      {
        "errorClass": "String",
        "errorType": "String",
        "errorCode": "String",
        "errorMessage": "String"
      }
    ]
  }
}

querycontractdetails

This API returns synchronously returns the contract details matching the input criteria.

The response is contract Details matching the input criteria.

{
  "queryContractDetailsRequest": {
    "appID": "string",
    "requestDateTime": "string",
    "customerUniqueTransactionID": "string",
    "customerSourceID": "string",
    "contractNumber": "string"
  }
}
HTTP status code - 200
{
  "queryContractDetailsResponse": {
    "responseDateTime": "string",
    "customerUniqueTransactionID": "string",
    "customerSourceID": "string",
    "statusCode": "200",
    "status": "Success",
    "message": "Successfully processed the request",
    "data": {
      "contractNumber": "number",
      "contractCreateDate": "string",
      "contractLastModifiedDate": "string",
      "contractStatus": "string",
      "contractStartDate": "string",
      "contractEndDate": "string",
      "lineItemCount": "number",
      "lineItems": [
        {
          "itemNumber": "number",
          "serialNumber": "string",
          "ssrn": "string",
          "productSKU": "string",
          "productSKUdescription": "string",
          "serviceSKU": "string",
          "serviceSKUdescription": "string",
          "serviceType": "string",
          "itemStatus": "string",
          "itemStartDate": "string",
          "itemEndDate": "string",
          "itemRenewed": "string",
          "activationId": "string",
          "productSKUeolDate": "string",
          "productSKUeosDate": "string",
          "serviceSKUeolDate": "string",
          "serviceSKUeosDate": "string",
          "serviceSKUshipmentServiceLevel": "string",
          "installedAtId": "number",
          "installedAtName": "string",
          "installedAtAddressLine1": "string",
          "installedAtCity": "string",
          "installedAtStateRegionProvince": "string",
          "installedAtPostalCode": "string",
          "installedAtCountry": "string",
          "itemContractAnnualizedNet": "string",
          "productSKUListPrice": "string",
          "productSKUListPriceCurrency": "string",
          "productReplacementSKU": "string"
        },
        {
          "itemNumber": "number",
          "serialNumber": "string",
          "ssrn": "string",
          "productSKU": "string",
          "productSKUdescription": "string",
          "serviceSKU": "string",
          "serviceSKUdescription": "string",
          "serviceType": "string",
          "itemStatus": "string",
          "itemStartDate": "string",
          "itemEndDate": "string",
          "itemRenewed": "string",
          "activationId": "string",
          "productSKUeolDate": "string",
          "productSKUeosDate": "string",
          "serviceSKUeolDate": "string",
          "serviceSKUeosDate": "string",
          "serviceSKUshipmentServiceLevel": "string",
          "installedAtId": "number",
          "installedAtName": "string",
          "installedAtAddressLine1": "string",
          "installedAtCity": "string",
          "installedAtStateRegionProvince": "string",
          "installedAtPostalCode": "string",
          "installedAtCountry": "string",
          "itemContractAnnualizedNet": "string",
          "productSKUListPrice": "string",
          "productSKUListPriceCurrency": "string",
          "productReplacementSKU": "string"
        }
      ]
    }
  }
}
HTTP status code - 400
{
  "queryContractDetailsResponse": {
    "responseDateTime": "String",
    "customerUniqueTransactionID": "String",
    "customerSourceID": "String",
    "message": "Error in processing the request",
    "status": "Error",
    "statusCode": "400",
    "fault": [
      {
        "errorClass": "String",
        "errorType": "String",
        "errorCode": "String",
        "errorMessage": "String"
      }
    ]
  }
}

querycontractbulkdata

This API returns synchronously returns the bulk Contract data S3 file links matching the input criteria.

The input criteria is date range within the last one to seven days where current day is day zero.

The response is links to the AWS S3 files matching the input criteria. The response is returned in a single payload with no pagination.

Net new changes for the last 24 hours will be generated daily at the end of the day. The files generated will be retained for seven days. Assuming current day is day zero, Clients will be able to pull files for the last one to seven days.

Search criteria precedence is as follows:

Options snapshotFromDate snapshotToDate AWS S3 links returned
1 Yes Yes snapshotToDate – snapshotFromDate <= last 7 days:links to data files extracted for the matching days
snapshotToDate – snapshotFromDate > last 7 days, validation error
2 Yes No If currentDate – snapshotFromDate <= 7 days, return S3 links to data files.
If currentDate – snapshotFromDate > 7 days, validation error
{
  "contractsBulkDataRequest" : {
    "appId" : "String",
    "requestDateTime" : "String",
    "customerUniqueTransactionID" : "String",
    "customerSourceID" : "String",
    "snapshotFromDate" : "String",
    "snapshotToDate" : "String"
  }
}
HTTP status code - 200
{
  "contractsBulkDataResponse": {
    "responseDateTime": "String",
    "customerSourceID": "String",
    "customerUniqueTransactionID": "String",
    "statusCode": "200",
    "status": "Success",
    "message": "Successfully processed the request",
    "data": {
      "noDataFound": [
        {
          "snapshotDate": "String",
          "message": "String"
        },
        {
          "snapshotDate": "String",
          "message": "String"
        }
      ],
      "links": [
        {
          "url": "String",
          "snapshotDate": "String",
          "urlValidFromDateTime": "String",
          "urlValidToDateTime": "String"
        },
        {
          "url": "String",
          "snapshotDate": "String",
          "urlValidFromDateTime": "String",
          "urlValidToDateTime": "String"
        }
      ]
    }
  }
}
HTTP status code - 400
{
  "contractsBulkDataResponse": {
    "responseDateTime": "String",
    "customerUniqueTransactionID": "String",
    "customerSourceID": "String",
    "message": "Error in processing the request",
    "status": "Error",
    "statusCode": "400",
    "fault": [
      {
        "errorClass": "String",
        "errorType": "String",
        "errorCode": "String",
        "errorMessage": "String"
      }
    ]
  }
}

JSON Key Details

API1 - queryContracts
API2 - queryContractDetails
API3 - queryContractsBulkData

Request

JSON Key API1 API2 API3 Data Type Description/Comments
appId X X X String
requestDateTime X X X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time
customerUniqueTransactionID X X X String
customerSourceID X X X String
contractsFromDateTime X X X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time
contractsToDateTime X X X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time
contractNumber X X X ArrayObject
salesOrderNumber X X ArrayObject
purchaseOrderNumber X X ArrayObject
contractStatus X X String
contractStartDate X X String YYYY-MM-DD
contractEndDate X X String YYYY-MM-DD
snapshotFromDate X String YYYY-MM-DD
snapshotToDate X String YYYY-MM-DD

Response

JSON Key API1 API2 API3 Data Type Description/Comments
queryContractsResponse X X X String
responseDateTime X X X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time
customerUniqueTransactionID X X X String
customerSourceID X X X String
status X X X String
statusCode X X X String
message X X X String
fault X X X ArrayObject (Optional)
errorType X X X String
errorClass X X X String
errorCode X X X String
errorMessage X X X String
data X X X Object
invalidContractNumbers X ArrayObject (within "data", Optional)
contractNumber X X String
invalidSalesOrderNumbers X ArrayObject (within "data", Optional)
invalidPurchaseOrderNumbers X ArrayObject (within "data", Optional)
contracts X ArrayObject (within "data", Optional)
contractCreatedDate X String
contractLastModifiedDate X X String
contractType X String
contractStatus X X String
contractStartDate X X String YYYY-MM-DD
contractEndDate X X String YYYY-MM-DD
renewed X String
salesOrderNumber X String
purchaseOrderNumber X String
endCustomerId X String
endCustomerName X String
endCustomerAddressLine1 X String
endCustomerCity X String
endCustomerStateRegionProvince X String
endCustomerPostalCode X String
endCustomerCountry X String
resellerId X String
resellerVarId X String
resellerName X String
resellerAddressLine1 X String
resellerCity X String
resellerStateRegionProvince X String
resellerPostalCode X String
resellerCountry X String
distributorId X String
distributorName X String
distributorAddressLine1 X String
distributorCity X String
distributorStateRegionProvince X String
distributorPostalCode X String
distributorCountry X String
juniperContactName X String
contractCreateDate X String
lineItemCount X String
lineItems X ArrayObject (within "data")
itemNumber X String
serialNumber X String
ssrn X String
productSKU X String
productSKUdescription X String
serviceSKU X String
serviceSKUdescription X String
serviceType X String
itemStatus X String
itemStartDate X String YYYY-MM-DD
itemEndDate X String YYYY-MM-DD
itemRenewed X String
activationId X String
productSKUeolDate X String YYYY-MM-DD
productSKUeosDate X String YYYY-MM-DD
serviceSKUeolDate X String YYYY-MM-DD
serviceSKUeosDate X String YYYY-MM-DD
serviceSKUshipmentServiceLevel X String
installedAtId X String
installedAtName X String
installedAtAddressLine1 X String
installedAtCity X String
installedAtStateRegionProvince X String
installedAtPostalCode X String
installedAtCountry X String
productReplacementSKU X String
noDataFound X ArrayObject (within "data", Optional)
snapshotDate X String YYYY-MM-DD
links X ArrayObject (within "data")
url X String
urlValidFromDateTime X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time
urlValidToDateTime X String (YYYY-MM-DDTHH:dd:ss.SSSZ), ZULU/UTC time

Error Messages

errorType errorClass errorCode errorMessage
Error Validation 900 Mandatory key - appId - is not provided.
Error Validation 902 Mandatory key - requestDateTime - is not provided.
Error Validation 903 Mandatory key - requestDateTime - format is incorrect. Please provide it in YYYY-MM-DDTHH:mm:ss.SSSZ format.
Error Validation 906 Mandatory key - customerSourceID - is not provided.
Error Validation 907 appId and customerSourceID combination is not valid.
Error Validation 908 Mandatory key - customerUniqueTransactionID - is not provided.
Error Validation 935 Mandatory key - appId - is invalid.
Error Validation 937 Invalid authentication method.
Error Validation 955 Duplicate customerUniqueTransactionID detected. Please provide an unique transaction ID.
Error Validation 980 Mandatory key - snapshotFromDate or snapshotToDate - is not provided.
Error Validation 981 Mandatory key - snapshotFromDate or snapshotToDate - format is incorrect. Please provide in the YYYY-MM-DD format.
Error Validation 985 Account Identifier validation failed.
Error Validation 986 Mandatory key - customerUniqueTransactionID - is invalid. Please use only alphanumeric characters.
Error Validation 993 Mandatory Key - contractNumber - is not provided.
Error Validation 994 Mandatory key - contractsFromDateTime and/or contractsToDateTime - format is incorrect. Please provide it in YYYY-MM-DDTHH:mm:ss.SSSZ format.
Error Validation 995 Mandatory key - Maximum allowed Ids per request exceeded. contractNumbers or salesOrderNumbers or purchaseOrderNumbers are mutually exclusive. Call API with one of these types of Ids and with upto a 1000 or less per request.
Error Validation 996 Optional key - contractStartDate or contractEndDate - format is incorrect. Please provide in the YYYY-MM-DD format.
Error Validation 997 Optional key - contractStatus - provided is invalid.
Error Validation 998 Mandatory Search Criteria - Missing one of the two required dateTimes. Populate both contractsFromDateTime and contractsToDateTime.
Error Validation 9001 Mandatory Search Criteria - contractsFromDateTime and contractsToDateTime, contractNumbers, salesOrderNumbers, purchaseOrderNumbers keys are mutually exclusive. Call API with only one of these and make sure they're not empty.
Error Validation 9002 Mandatory Search Criteria - dateTime range provided in UTC is not within the last 24 hours. Ensure that contractsFromDateTime and contractsToDateTime are in UTC and within the last 24 hours.
Error Validation 9003 Mandatory Search Criteria - contractsFromDateTime and contractsToDateTime range invalid.
Error Validation 9004 Optional Search Criteria - contractStartDate and contractEndDate range invalid.
Error Validation 9005 Mandatory key - contractNumber or salesOrderNumber or purchaseOrderNumber - provided is invalid.