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 /sys/api/v1/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 /sys/api/v1/business-objects/{businessObjectName}

HTTP Request

GET /sys/api/v1/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)

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"
            }
        ]
    },
    ...
]

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

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 retrieve

The string passed as businessObjectName is case sensitive and must match the corresponding class name. AccountType is a valid value whereas accounttype will return a 404

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.

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 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 /sys/api/v1/business-objects/BatchFile/1234

A binary file is provided for the requested business object

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

{
    "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 /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

The string passed as businessObjectName has the same restrictions above GET request to get all business objects

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 /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

The string passed as businessObjectName has the same restrictions above GET request to get all business objects

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/v1/business-object/{businessObjectName}

Creates a new business object

HTTP Request

POST /sys/api/v1/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.

Only a single business object is currently supported, BatchJobStatus. Creating such an object will schedule a batch job to run. The currently required parameters for this Business Object is name and group to start such a job.

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 /sys/api/v1/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 /sys/api/v1/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 /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": {
        "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 /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 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 /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 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 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 /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 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`