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 acquired 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 Available Business Objects

Example results for /api/business-objects

[
    "HigherEducationFunction",
    "ObjectCodeCurrent",
    "LaborObject",
    "CustomerAddressType",
    "AccountingPeriod",
    "VendorInactiveReason",
    "SufficientFundsCode",
    "AICPAFunction",
    "FiscalYearFunctionControl",
    "PostalCode",
    "AssetAcquisitionType",
    "ProposalStatus",
    "ShippingSpecialCondition",
    "TaxRegion",
    "AssetTransactionType",
    "State",
    "OwnershipCategory",
    ...
]

Returns a list of Business objects that can be queried via /api/business-objects/{businessObjectName}

HTTP Request

GET /api/business-objects/

Accept

Value Description
*/* Returns the results in json form
application/json Returns the results in json form

Get All Business Objects (by Type)

JSON API Results Response Definition

Property Description
recordCount The total number of records for the current request
pageSize The page size for the current request. Driven by limit query parameter. Defaults to 100
currentPage The current 0-indexed page of data for the current request. Driven by skip query parameter. Defaults to 0
messages Any informational and warning messages for the current request
messages.info Informational messages for the current request. A list of strings
messages.warning Warning messages for the current request. A list of strings
data Results for the current request

Example response for /api/business-objects/AccountType with Accept header set to application/json

{
    "recordCount": 350,
    "pageSize": 100,
    "currentPage": 0,
    "messages": {
        "info": [],
        "warning": []
    },
    "data": [
        {
            "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 response for /api/business-objects/AccountType with Accept header set to application/vnd.kuali.lookup+json

{
    "recordCount": 350,
    "pageSize": 100,
    "currentPage": 0,
    "messages": {
        "info": [],
        "warning": []
    },
    "data": [
        {
            "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"
                }
            ]
        },
        ...
    ]
}

Returns a list of business objects filtered by any search criteria provided

HTTP Request

GET /api/business-objects/{businessObjectName}

URI Parameters

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

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. Kuali Financials has a configurable upper limit for the maximum results to be returned. The default value for this limit is 250 items. To retrieve more items, use the skip parameter to page through all possible values.
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 indices 200-300 instead of 0-100. Negative values are ignored.

Responses

Code Name Description
200 Success A response similar to the above example will be returned
401 Unauthorized You do not have a valid authentication token
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 retrieval
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 /api/business-objects/BatchFile/1234

A binary file is provided for the requested business object

Example results for /api/business-objects/AccountType/014F3DAF81D8A448E043814FD28EA448

{
    "recordCount": 1,
    "pageSize": 100,
    "currentPage": 0,
    "messages": {
        "info": [],
        "warning": []
    },
    "data": [
        {
            "versionNumber": 1,
            "objectId": "014F3DAF81D8A448E043814FD28EA448",
            "lastUpdatedTimestamp": 1246420800000,
            "newCollectionRecord": false,
            "extension": null,
            "accountTypeCode": "AI",
            "accountTypeName": "A-21 ACTIVITY IDENTIFIER",
            "active": true
        }
    ]
}

Retrieves an instance of a business object. This supports both file downloads for some business objects (e.g. BatchFile with application/octet Accept header) and json details for the majority of Business Objects.

HTTP Request

GET /api/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
*/* Return the value of the business object in a json format
application/json Return the value of the business object in a json format
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
401 Unauthorized You do not have a valid authentication token
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 retrieval

Delete a Business Object

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

HTTP Request

DELETE /api/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
401 Unauthorized You do not have a valid authentication token
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

Create a new Business Object

Example results for `sys/api/business-object/{businessObjectName}

Creates a new business object

HTTP Request

POST /api/business-objects/{businessObjectName}

Body Parameters

Parameters should be provided via an application/json encoded body on the request. Each business object has its own set of required parameters. Consult the individual business object for the necessary data to provide.

Accept

Value Description
*/* Returns the results in json form
application/json Returns the results in json form

Response Headers

Name Description
Location A url with the location where the newly created business object can be found

Responses

Code Name Description
201 Created The object creation was successful. Consult the Location header for more information about the object
401 Unauthorized You do not have a valid authentication token
400 Bad Request There was an error with the request to create the object. Often times this is a result of incorrect data being provided
403 Forbidden You do not have access to create specific business object
501 Not Implemented The specified business object does not support creation

Details

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

Details

Example results for /api/business-objects/AccountType/details

{
  "title": "Account Type",
  "sections": [
    {
      "attributes": [
        {
          "name": "accountTypeCode",
          "label": "Account Type Code",
          "type": "STRING"
        },
        {
          "name": "accountTypeName",
          "label": "Account Type Name",
          "type": "STRING"
        },
        {
          "name": "active",
          "label": "Status",
          "type": "BOOLEAN"
        }
      ],
      "title": null
    }
  ]
}

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

HTTP Request

GET /api/business-objects/{businessObjectName}/details

URI Parameters

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

Responses

Code Name Description
200 Success A response similar to the above example will be returned
401 Unauthorized You do not have a valid authentication token
403 Forbidden You do not have access to the specified business object
404 Not Found The specified business object does not exist

Lookups

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

Lookup

Example results for /api/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": {
        "maxLength": -1,
        "exactLength": 2,
        "allowWhitespace": false,
        "allowUnderscore": false,
        "allowPeriod": false,
        "allowParenthesis": false,
        "allowDollar": false,
        "allowForwardSlash": false,
        "lowerCase": false,
        "allowDash": false
      },
      "label": "Account Type Code",
      "name": "accountTypeCode",
      "required": true,
      "shortLabel": "Account Type",
      "canLookup": false,
      "control": {
          "type": null
      },
      "disableLookup": false
    },
    {
      "type": "STRING",
      "forceUppercase": false,
      "maxLength": 40,
      "validationPattern": {
        "maxLength": -1,
        "exactLength": -1,
        "allowWhitespace": true
      },
      "label": "Account Type Name",
      "name": "accountTypeName",
      "required": true,
      "shortLabel": "Name",
      "canLookup": false,
      "control": {
          "type": null
      },
      "disableLookup": false
    },
    {
      "type": "BOOLEAN",
      "forceUppercase": false,
      "label": "Status",
      "name": "active",
      "required": false,
      "shortLabel": "active",
      "defaultValue": "Y",
      "canLookup": false,
      "control": {
          "type": "RADIO"
      },
      "disableLookup": false
    }
  ],
  "results": {
    "fields": [
      {
        "type": "STRING",
        "forceUppercase": true,
        "maxLength": 2,
        "validationPattern": {
          "maxLength": -1,
          "exactLength": 2,
          "allowWhitespace": false,
          "allowUnderscore": false,
          "allowPeriod": false,
          "allowParenthesis": false,
          "allowDollar": false,
          "allowForwardSlash": false,
          "lowerCase": false,
          "allowDash": false
        },
        "label": "Account Type Code",
        "name": "accountTypeCode",
        "required": true,
        "shortLabel": "Account Type",
        "disableInquiry": false
      },
      {
        "type": "STRING",
        "forceUppercase": false,
        "maxLength": 40,
        "validationPattern": {
          "maxLength": -1,
          "exactLength": -1,
          "allowWhitespace": true
        },
        "label": "Account Type Name",
        "name": "accountTypeName",
        "required": true,
        "shortLabel": "Name",
        "disableInquiry": false
      },
      {
        "type": "BOOLEAN",
        "forceUppercase": false,
        "label": "Status",
        "name": "active",
        "required": false,
        "shortLabel": "active",
        "disableInquiry": false
      }
    ],
    "defaultSortFields": ["accountTypeCode"]
  }
}

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

HTTP Request

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

URI Parameters

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

Responses

Code Name Description
200 Success A response similar to the above example will be returned
401 Unauthorized You do not have a valid authentication token
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 /api/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 above Lookup

HTTP Request

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

URI Parameters

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

Responses

Code Name Description
200 Success A response similar 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
401 Unauthorized You do not have a valid authentication token
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 /api/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 /api/business-objects/{businessObjectName}/lookup/values/{attributeDefinitionName}

URI Parameters

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

Responses

Code Name Description
200 Success A response similar to the above example will be returned. If there are no values for the a valid attribute name, an empty object will be returned
401 Unauthorized You do not have a valid authentication token
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 attribute matching attributeDefinitionName
json