NAV Navbar
json

Introduction

Welcome to the Kuali Financials API.

Authentication

In order to interact with the included APIs a token will need to be provided in the header of each request. Each institution is configured with a different authentication mechanism therefore the way in which the token is acquired will depend on your institution. Once you have aquired your token, you will need to add the following header to each request:

Authorization: Bearer {authorizationToken}

Business Objects

All business object endpoints require a valid authentication token. More information can be found here

Get All Business Objects (by Type)

Example results for /sys/api/v1/business-objects/AccountType with Accept header set to application/json

[
    {
        "versionNumber": 1,
        "objectId": "014F3DAF81D8A448E043814FD28EA448",
        "lastUpdatedTimestamp": 1246428000000,
        "newCollectionRecord": false,
        "accountTypeCode": "AI",
        "accountTypeName": "A-21 ACTIVITY IDENTIFIER",
        "active": true
    },
    {
        "versionNumber": 1,
        "objectId": "014F3DAF81D9A448E043814FD28EA448",
        "lastUpdatedTimestamp": 1246428000000,
        "newCollectionRecord": false,
        "accountTypeCode": "BS",
        "accountTypeName": "BALANCE SHEET ACCOUNT",
        "active": true
    },
    {
        "versionNumber": 1,
        "objectId": "014F3DAF81DAA448E043814FD28EA448",
        "lastUpdatedTimestamp": 1246428000000,
        "newCollectionRecord": false,
        "accountTypeCode": "DP",
        "accountTypeName": "DISTINGUISHED PROFESSORSHIP ACCOUNTS",
        "active": true
    },
    ...
]

Example results for /sys/api/v1/business-objects/AccountType with Accept header set to application/vnd.kuali.lookup+json

[
    {
        "accountTypeCode": {
            "type": "inquiry",
            "url": "kr/inquiry.do?accountTypeCode=AI&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&versionNumber=1&methodToCall=start",
            "value": "AI"
        },
        "accountTypeName": "A-21 ACTIVITY IDENTIFIER",
        "active": true,
        "actions": [
            {
                "label": "Edit",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=AI&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=edit"
            },
            {
                "label": "Copy",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=AI&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=copy"
            }
        ]
    },
    {
        "accountTypeCode": {
            "type": "inquiry",
            "url": "kr/inquiry.do?accountTypeCode=BS&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&versionNumber=1&methodToCall=start",
            "value": "BS"
        },
        "accountTypeName": "BALANCE SHEET ACCOUNT",
        "active": true,
        "actions": [
            {
                "label": "Edit",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=BS&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=edit"
            },
            {
                "label": "Copy",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=BS&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=copy"
            }
        ]
    },
    {
        "accountTypeCode": {
            "type": "inquiry",
            "url": "kr/inquiry.do?accountTypeCode=DP&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&versionNumber=1&methodToCall=start",
            "value": "DP"
        },
        "accountTypeName": "DISTINGUISHED PROFESSORSHIP ACCOUNTS",
        "active": true,
        "actions": [
            {
                "label": "Edit",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=DP&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=edit"
            },
            {
                "label": "Copy",
                "method": "GET",
                "url": "kr/maintenance.do?accountTypeCode=DP&businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=copy"
            }
        ]
    },
    ...
]

HTTP Request

GET /sys/api/v1/business-objects/{businessObjectName}

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retreive

Request Headers

Accept

Value Description
*/* Returns the results in json form
application/json Returns the results in json form
application/vnd.kuali.lookup+json Returns the results in json form with additional lookup-specific annotations (actions, inquiries, etc)
text/csv Returns the results as a binary file in comma separated format

Filtering query parameters

Each business object has a set of properties that can be used to filter the results returned. These properties are unique to the business object. The available parameters can be found in the form value from the [lookup endpoint]

Universal Query Parameters

There are several parameters that all business objects support

Parameter Default Description
sort none An attribute on the business object to sort the results by. The default sort order is ascending. If a descending order is desired, prefix the value with a minus sign sort=-lastUpdatedDate
limit 100 The maximum number of results to return. Negative values are ignored.
skip 0 When there are more business objects available in the results set than returned, you can set the skip value to choose the index of where the results start. For instance, if skip=200 the results will return will return the matching business objects at indicies 200-300 instead of 0-100. Negative values are ignored.

Response Headers

Name Description
Item-count A number indicating how many total results are available for a given query. This value can be used to determine when the upper limit for skip and limit will be reached

Responses

Code Name Description
200 Success A response similiar to the above example will be returned
403 Forbidden You do not have access to the specified business object
404 Not Found The specified business object does not exist
405 Method Not Allowed The specified business object does not support retrevial
416 Range not Satisfiable The value provided for the skip query parameter exceeds the total amount of results allowed

Get A Specific Business Object

Example results for /sys/api/v1/business-objects/BatchFile/1234

A binary file is provided for the requested business object

Retrieves an instance of a business object. Currently very limited support. At this time, only file downloads for some business objects are supported.

HTTP Request

GET /sys/api/v1/business-objects/{businessObjectName}/{id}

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retrieve
id string true The identifier for the business object of the provided type

Request Headers

Accept

Name Description
application/octet Return the value of the business object in a binary file format

Responses

Code Name Description
200 Success The business object was successfully returned
403 Forbidden You do not have access to this specific business object
404 Not Found The specified business object does not exist
405 Method Not Allowed The specified business object does not support retrevial

Delete a Business Object

Deletes a business object of the provided type with the provided identifiier

HTTP Request

DELETE /sys/api/v1/business-objects/{businesObjectName}/{id}

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retrieve
id string true The identifier for the business object of the provided type

Responses

Code Name Description
204 No Content The deletion was successful and there is no longer any content at the requested URL
403 Forbidden You do not have access to this specific business object
404 Not Found The specified business object does not exist
405 Method Not Allowed The specified business object does not support deletion

Lookups

All lookup endpoints require a valid authentication token. More information can be found here

Lookup

Example results for /sys/api/v1/business-objects/AccountType/lookup

{
  "title": "Account Type Lookup",
  "create": {
    "url":
      "kr/maintenance.do?businessObjectClassName=org.kuali.kfs.coa.businessobject.AccountType&methodToCall=start",
    "label": "Create New"
  },
  "form": [
    {
      "type": "STRING",
      "forceUppercase": true,
      "maxLength": 2,
      "validationPattern": {
        "allowWhitespace": false,
        "allowUnderscore": false,
        "allowPeriod": false,
        "allowParenthesis": false,
        "allowDollar": false,
        "allowForwardSlash": false,
        "lowerCase": false,
        "allowDash": false,
        "maxLength": -1,
        "exactLength": 2
      },
      "control": {
        "datePicker": false,
        "expandedTextArea": false,
        "size": 2,
        "ranged": true
      },
      "name": "accountTypeCode",
      "label": "Account Type Code",
      "shortLabel": "Account Type",
      "required": true
    },
    {
      "type": "STRING",
      "forceUppercase": false,
      "maxLength": 40,
      "validationPattern": {
        "allowWhitespace": true,
        "maxLength": -1,
        "exactLength": -1
      },
      "control": {
        "datePicker": false,
        "expandedTextArea": false,
        "size": 50,
        "ranged": true
      },
      "name": "accountTypeName",
      "label": "Account Type Name",
      "shortLabel": "Name",
      "required": true
    },
    {
      "defaultValue": "Y",
      "type": "BOOLEAN",
      "forceUppercase": false,
      "maxLength": 1,
      "control": {
        "isRadio": true,
        "datePicker": false,
        "expandedTextArea": false,
        "valuesFinderClass":
          "org.kuali.kfs.krad.keyvalues.IndicatorYNBothValuesFinder",
        "ranged": true
      },
      "formatterClass": "org.kuali.rice.core.web.format.BooleanFormatter",
      "name": "active",
      "label": "Active Indicator",
      "shortLabel": "active",
      "required": false
    }
  ],
  "results": {
    "fields": [
      {
        "disableInquiry": false,
        "type": "STRING",
        "forceUppercase": true,
        "maxLength": 2,
        "validationPattern": {
          "allowWhitespace": false,
          "allowUnderscore": false,
          "allowPeriod": false,
          "allowParenthesis": false,
          "allowDollar": false,
          "allowForwardSlash": false,
          "lowerCase": false,
          "allowDash": false,
          "maxLength": -1,
          "exactLength": 2
        },
        "control": {
          "datePicker": false,
          "expandedTextArea": false,
          "size": 2,
          "ranged": true
        },
        "name": "accountTypeCode",
        "label": "Account Type Code",
        "shortLabel": "Account Type",
        "required": true
      },
      {
        "disableInquiry": false,
        "type": "STRING",
        "forceUppercase": false,
        "maxLength": 40,
        "validationPattern": {
          "allowWhitespace": true,
          "maxLength": -1,
          "exactLength": -1
        },
        "control": {
          "datePicker": false,
          "expandedTextArea": false,
          "size": 50,
          "ranged": true
        },
        "name": "accountTypeName",
        "label": "Account Type Name",
        "shortLabel": "Name",
        "required": true
      },
      {
        "disableInquiry": false,
        "type": "BOOLEAN",
        "forceUppercase": false,
        "maxLength": 1,
        "control": {
          "datePicker": false,
          "expandedTextArea": false,
          "ranged": true
        },
        "formatterClass": "org.kuali.rice.core.web.format.BooleanFormatter",
        "name": "active",
        "label": "Active Indicator",
        "shortLabel": "active",
        "required": false
      }
    ],
    "defaultSortFields": ["accountTypeCode"]
  }
}

Returns a JSON serialization of the lookup form associated with a Financials business object.

HTTP Request

GET /sys/api/v1/business-objects/{businessObjectName}/lookup

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retreive

Responses

Code Name Description
200 Success A response similiar to the above example will be returned
403 Forbidden You do not have access to the specified business object
404 Not Found The specified business object does not exist

Lookup All Control Values

Example results for /sys/api/v1/business-objects/Award/lookup/values

{
  "grantDescriptionCode": [
    {
      "key": "",
      "value": "",
      "disabled": false
    },
    {
      "key": "C",
      "value": "C - Federal Contract",
      "disabled": false
    },
    {
      "key": "G",
      "value": "G - Federal Grant",
      "disabled": false
    },
    {
      "key": "N",
      "value": "N - Non Federal Grant",
      "disabled": false
    },
    {
      "key": "NPT",
      "value": "NPT - Non Fed Fed-Pass-T Grant",
      "disabled": false
    },
    {
      "key": "O",
      "value": "O - Non Federal Contract",
      "disabled": false
    },
    {
      "key": "OPT",
      "value": "OPT - Non Fed Fed-Pass-T Contr",
      "disabled": false
    },
    {
      "key": "U",
      "value": "U - University Internal",
      "disabled": false
    }
  ],
  "awardStatusCode": [
    {
      "key": "",
      "value": "",
      "disabled": false
    },
    {
      "key": "A",
      "value": "A-Award",
      "disabled": false
    },
    {
      "key": "R",
      "value": "R-Rejected",
      "disabled": false
    },
    {
      "key": "U",
      "value": "U-Underwrite",
      "disabled": false
    },
    {
      "key": "W",
      "value": "W-Withdrawn",
      "disabled": false
    }
  ],
  "awardPurposeCode": [
    {
      "key": "",
      "value": "",
      "disabled": false
    },
    {
      "key": "A",
      "value": "A-INSTRUCTION",
      "disabled": false
    },
    {
      "key": "C",
      "value": "C-RESEARCH",
      "disabled": false
    },
    {
      "key": "F",
      "value": "F-SERVICE/OTHER",
      "disabled": false
    },
    {
      "key": "G",
      "value": "G-ACADEMIC SUPPORT",
      "disabled": false
    },
    {
      "key": "H",
      "value": "H-STUDENT SERVICES",
      "disabled": false
    },
    {
      "key": "S",
      "value": "S-SCHOLARSHIPS & FELLOWSHIPS",
      "disabled": false
    },
    {
      "key": "X",
      "value": "X-DEFAULT",
      "disabled": false
    }
  ],
  "billingFrequencyCode": [
    {
      "key": "",
      "value": "",
      "disabled": false
    },
    {
      "key": "ANNU",
      "value": "Annually",
      "disabled": false
    },
    {
      "key": "LOCB",
      "value": "LOC Billing",
      "disabled": false
    },
    {
      "key": "MILE",
      "value": "Milestone",
      "disabled": false
    },
    {
      "key": "MNTH",
      "value": "Monthly",
      "disabled": false
    },
    {
      "key": "PDBS",
      "value": "Predetermined Billing Schedule",
      "disabled": false
    },
    {
      "key": "QUAR",
      "value": "Quarterly",
      "disabled": false
    },
    {
      "key": "SEMI",
      "value": "Semi Annually",
      "disabled": false
    }
  ]
}

Returns a JSON serialization of the values for all attribute definitions on the lookup form of a business object. These values correspond to applicable keys form property of the the above Lookup

HTTP Request

GET /sys/api/v1/business-objects/{businessObjectName}/lookup/values

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retreive

Responses

Code Name Description
200 Success A response similiar to the above example will be returned. If the requested business object does not have any values associated with its attribute definitions, the result will be an empty object
403 Forbidden You do not have access to the specified business object
404 Not Found The specified business object does not exist

Lookup A Single Control Value

Example results for /sys/api/v1/business-objects/Award/lookup/values/grantDescriptionCode

[
  {
    "key": "",
    "value": "",
    "disabled": false
  },
  {
    "key": "C",
    "value": "C - Federal Contract",
    "disabled": false
  },
  {
    "key": "G",
    "value": "G - Federal Grant",
    "disabled": false
  },
  {
    "key": "N",
    "value": "N - Non Federal Grant",
    "disabled": false
  },
  {
    "key": "NPT",
    "value": "NPT - Non Fed Fed-Pass-T Grant",
    "disabled": false
  },
  {
    "key": "O",
    "value": "O - Non Federal Contract",
    "disabled": false
  },
  {
    "key": "OPT",
    "value": "OPT - Non Fed Fed-Pass-T Contr",
    "disabled": false
  },
  {
    "key": "U",
    "value": "U - University Internal",
    "disabled": false
  }
]

returns a JSON serialization of the values for a specified attribute definition on the lookup form of a business object.

HTTP Request

GET /sys/api/v1/business-objects/{businessObjectName}/lookup/values/{attributeDefinitionName}

URI Parameters

Name Type Required Description
businessObjectName string true The name of the business object you want to retreive
attributeDefinitionName string true The name of the attribute definition values you would like to retrieve

Responses

Code Name Description
200 Success A response similiar to the above example will be returned. If there are no values for the a valid attribute name, an empty object will be returned
403 Forbidden You do not have access to the specified business object
404 Not Found The specified business object does not exist or no lookup exists for the or the business object does not have an attirbute matching attributeDefinitionName