Workflow API

Authentication and Authorization NEW

With the looming retirement of UIP, Workflow no longer uses Oauth2 for authentication/authorization. Instead, we have converted to using Basic auth for API client authentication. Authorization is then handled with the use of a few new headers. See the full details below.

Authentication

To authenticate with Workflow, the API client you've configured for your forms can now start using the header Authorization: Basic {credentials}. To request your Client ID and Client Secret credentials, please reach out to the Workflow team via email at its-workflow-support@uiowa.edu

Authorization

Workflow API endpoints no longer verify that the user you are making a request for is logged into any particular system like we did with Oauth2 user tokens. Instead, we defer to you as the developer to authenticate your users via the new trusted login services supported by the AIS Identity and Access Management (IAM) team. This means you now have the freedom to decide how actions are recorded in Workflow history via two new headers.

x-workflow-request-user - The person/client you are making the request as or on behalf of. Either a University ID or Client ID are accepted. This header is required for every request.

x-workflow-bypass-authorization A way to indicate that Workflow should not attempt to verify whether the request user has standard package rights, such as Approver, Initiator, or Admin rights. Accepted values are true or false. This header is optional.

Important! 🚨

If you chooses to utilize the bypass authorization feature, it is your application's responsibility to evaluate user access controls based on your own business rules. Workflow may still prevent you from performing certain actions based on the current state of a package.

Note

Workflow will continue to support the Package Actions endpoint that you can leverage to enable/disable certain features for a particular user.

Common Parameters

Some commonly referenced attributes used throughout the documentation

env - The deployment version of a form. Either 'test' or 'prod'.

formId - The ID that was assigned when you created your form

packageId - The ID of a specific package instance

Create a Package

Request URL

http

POST /workflow/{env}/api/developer/forms/{formId}/packages

Request Body

state - The initial state of the package. Allowed values are 'PRE_ROUTING', 'DRAFT', or 'ROUTING'. Defaults to 'ROUTING' if no value is sent. Setting state to 'ROUTING' will create the package and immediately begin routing.

subType - The sub-type of the package. This is required if your form has sub-types configured, otherwise it may be omitted.

emailContent Accepts a custom HTML string that will be inserted into each Approver notification when the package arrives in their inbox. This message will be inserted below the Package URL and above the Package Summary information. This is optional and can be omitted.

entry An object consisting of key/value pairs of all of the fields defined on the Form Integration page. You must pass all fields. Passing null values is allowed. Certain fields have specific format requirements, which are shown in the example below.

Example

RequestRequest BodySuccess Response (HTTP 201)Error Response 422

http

POST https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages

json

{
  "state" : "ROUTING",
  "subType": null,
  "emailContent": {
     "packageDetails": "<h3>My Custom HTML for the Approver Notification Email</h3>"
  },
  "entry" : {
        "text_field_natural_key" : "This is my example text",
        "date_field_natural_key" : "2014-08-09",
        "url_field_natural_key" : "https://workflow.uiowa.edu/help",
        "email_field_natural_key" : "myemail@uiowa.edu",
        "number_field_natural_key" : 10000,
        "currency_field_natural_key" : 2.24,
        "no_answer_field_natural_key" : null,
        "university_id_field_natural_key" : "00027147",
        "org_field_natural_key" : "05",
        "department_field_natural_key" : "05-0315",
        "sub_department_field_natural_key" : "05-0315-0001",
        "position_field_natural_key" : "00116359"
  },
}

json

{
    "id": 2,
    "state": "ROUTING",
    "subType": null,
    "emailContent": {
        "packageDetails": "<h3>My Custom HTML for the Approver Notification Email</h3>"
    },
    "actions": {
        "canView": true,
        "canEdit": true,
        "canSign": true,
        "canVoid": true,
        "canInitiatorVoid": false,
        "canAddApprover": true,
        "canVoidAfter": false,
        "packageId": 2,
        "signatureId": 2
    },
    "routingDate": "2015-04-20T16:46:37",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "voidReason": null,
    "commentCount": 0,
    "attachmentCount": 0
}

json

{
    "entry['number_field_natural_key']" : [ "validation.notFound" ],
    "entry['text_field_natural_key']" : [ "validation.required" ],
    "entry['person_field_natural_key']" : [ "validation.badAnswerType" ],
    "entry['office_field_natural_key']" : [ "validation.notFound" ],
    "entry['not_known']" : [ "validation.invalidValue" ]
}

Route an Existing Package

Start routing a package that was created with a PRE_ROUTING state. If calling on behalf of a person, only package initiator may use this endpoint to start routing the package.

Request

http

PUT /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}

Request Body

state - Must be set to "ROUTING"

subType - The sub-type of the package. This is required if your form has sub-types configured, otherwise it may be omitted.

Example

RequestRequest BodySuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/2

json

{
  "id" : 2,
  "state" : "ROUTING",
  "subType" : null,
  "emailContent" : {
    "packageDetails" : "<h3>My Custom HTML Message</h3>"
  }
}

json

{
    "id": 2,
    "state": "ROUTING",
    "voidReason": null,
    "actions": {
        "canView": true,
        "canEdit": true,
        "canSign": true,
        "canVoid": true,
        "canInitiatorVoid": false,
        "canAddApprover": true,
        "canVoidAfter": false,
        "packageId": 2,
        "signatureId": 2
    },
    "subType": null,
    "emailContent": {
        "packageDetails": "<h3>My Custom HTML Message</h3>"
    },
    "routingDate": "2015-04-20T16:46:37",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Get Basic Package Information

Retrieve basic information for a specific package. This endpoint does not return Entry Data or Routing History.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/2

json

{
  "id" : 2,
  "state" : "ROUTING",
  "voidReason" : null,
  "actions" : {
    "canView" : true,
    "canEdit" : true,
    "canSign" : true,
    "canVoid" : true,
    "canInitiatorVoid" : false,
    "canAddApprover" : true,
    "canVoidAfter" : false,
    "packageId" : 2,
    "signatureId" : 2
  },
  "subType" : null,
  "emailContent" : {
    "packageDetails" : null
  },
  "routingDate" : "2015-04-20T16:46:37",
  "actionDate" : null,
  "initiator" : {
    "id" : 9,
    "displayName" : "Simpson, Homer J",
    "hrdeptdesc" : null,
    "collegeName" : null,
    "personType" : null,
    "title" : null,
    "univid" : "00028152",
    "email" : "homer-j-simpson@uiowa.edu",
    "campusPostalAddress" : null,
    "officePhone" : null
  },
  "commentCount" : 0,
  "attachmentCount" : 0
}

Download a Package PDF

Download a PDF representation of the current package. Optionally include the package's routing history and/or pdf attachments. By default, routing information and attachments are excluded.

INFO

Take note, when requesting attachments that application/pdf is the only supported media type. Attachments of any other media type will not be included in the download.

When integrating with Form Builder Forms, if you would like to guarantee that all attachments get merged with the pdf, you can update your attachment settings in the form builder interface to only allow pdf files.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/pdf[?includeRouting=true|mergeAttachments=true]

Request Parameters

includeRouting - An optional query parameter to include the routing history table

mergeAttachments - An option query parameter to include any uploaded pdf attachments

Get Package History

Returns an array of destinations and actions that constitute the routing history of a particular package. Routing history is automatically available within the Workflow Widget for initiators and approvers.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/history

INFO

To retrieve the simulated future history of a package call /future_history. The resulting response will only include the calculated future route based on the package's current entry data and state.

Key Response Body Parameters

@class - The type of history event

actionDate - The timestamp of when the package was received by the user or the action was taken.

person - The person who received the package / performed the action.

permission - The signature rights of the user. Will be one of the following: "SIGNATURE_REQUIRED", "SIGNATURE_PERMITTED', "VIEW_AND_EDIT", "VIEW_ONLY"

context - If applicable, this will include details on how / why this approver received the package.

office - If applicable, this will include the details of the office destination.

resolution - If applicable, will show who the role or position ultimately resolves to and can provide more context about destination.

Formatting & Displaying the Response Workflow provides a web component that can format the response of this endpoint for you. It will parse the json response and display the routing history similar to widget.

To format the response, first load the javascript helper file:

<script src="https://workflow.uiowa.edu/assets/dist/embeds/history/routing-history.js?cache=[Insert random string here for cache busting.]"></script>

Then place the <routing-history> tag on the page. In the history attribute pass in the JSON response you received from this endpoint.

html

<routing-history history="{{ history }}"></routing-history>

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/11/history

json

[
    {
        "@class": "initiation",
        "actionDate": "2015-04-20T16:46:46",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "stop": null
    },
    {
        "@class": "signature",
        "actionDate": "2015-04-20T16:46:47",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "stop": {
            "name": null,
            "stopNumber": 1
        },
        "permission": "SIGNATURE_REQUIRED",
        "context": null,
        "resolution": {
            "@class": "person",
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "routingDate": "2015-04-20T16:46:46",
        "office": null,
        "state": "BYPASSED_REMOVE",
        "autoSigned": null,
        "inboxSigned": null,
        "isInInbox": false
    },
    {
        "@class": "void",
        "actionDate": "2015-04-20T16:46:46",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        }
    },
    {
        "@class": "unvoid",
        "actionDate": "2015-04-20T16:46:46",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        }
    },
    {
        "@class": "remove",
        "actionDate": "2015-04-20T16:46:47",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "stop": {
            "name": "RemoveFromWorkflow",
            "stopNumber": 3
        }
    },
    {
        "@class": "re_initiate",
        "actionDate": "2015-04-20T16:46:47",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "stop": {
            "name": "Re-initiated",
            "stopNumber": 4
        }
    },
    {
        "@class": "signature",
        "actionDate": "2015-04-20T16:46:47",
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "stop": {
            "name": null,
            "stopNumber": 5
        },
        "permission": "SIGNATURE_REQUIRED",
        "context": null,
        "resolution": {
            "@class": "person",
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "routingDate": "2015-04-20T16:46:47",
        "office": null,
        "state": "APPROVED",
        "autoSigned": false,
        "inboxSigned": false,
        "isInInbox": false
    },
    {
        "@class": "complete",
        "actionDate": "2015-04-20T16:46:47"
    }
]

Get User's Allowed Package Actions

This endpoint returns a list of all allowed actions that the current user can take on a specified package. This is very useful for enforcing Workflow rights within your application.

Request URL

Multiple packageIds can be passed.

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/actions?id={packageId1}&id={packageId2}

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/actions?id=17&id=18

json

[
    {
        "canView": true,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 17,
        "signatureId": null
    },
    {
        "canView": true,
        "canEdit": true,
        "canSign": true,
        "canVoid": true,
        "canInitiatorVoid": false,
        "canAddApprover": true,
        "canVoidAfter": false,
        "packageId": 18,
        "signatureId": 40
    }
]

Get Package Entry Data

Get the Entry Data associated with an existing package. If calling on behalf of a person, only the package initiator or an approver are allowed access unless you choose to bypass authorization.

Request URL

http

GET     /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/entry

Example

RequestSuccess Response

http

GET     https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/2/entry

json

{
    "entry": {
        "age": 50,
        "name": "Duffman"
    }
}

Update Package Entry Data

Update the entry data associated with an existing package

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/entry

Request Body

entry - An object consisting of key/value pairs of all of the fields defined on the Form Integration page. You must pass all fields. Passing null values is allowed. Certain fields have specific format requirements, which are shown in the example below.

sendDeltaEmail- Used in conjunction with deltaSummary to determine how edit email notifications are sent to current approvers.

emailContent > deltaSummary - Custom HTML string that will be inserted into each the edit notification email sent to all approvers. Can be set null.

emailContent > packageDetails - Custom HTML string that will be inserted into each Approver notification when the package arrives in their inbox. This message will be inserted below the Package URL and above the Package Summary information. A null value will be ignored and will not update the current packageDetails. To clear a previously set value send an empty string.

Delta Scenarios

sendDeltaEmail is true - A notification email will always be sent to all approvers, regardless if any acutal data changes occurred.

sendDeltaEmail is false - A notification email will not be sent to approvers. It is your application's responsibility to notify approvers of the edit if you chose.

sendDeltaEmail is null and deltaSummary is not null - A notification email will be sent with deltaSummary inserted into the message.

sendDeltaEmail is null and deltaSummary is null - A notification email will be sent only if there are data changes.

Example

RequestRequest BodySuccess ResponseValidation Error Response (HTTP 422)

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/2/entry

json

{
  "entry" : {
    "age" : 70.0,
    "name" : "Ned Flanders"
  },
  "sendDeltaEmail" : true,
  "emailContent" : {
    "deltaSummary" : "<h3>My custom HTML for the edit email</h3>",
    "packageDetails" : "<h3>My Custom HTML for the approver notification email</h3>"
  }  
}

json

{
    "entry": {
        "age": 70.0,
        "name": "Al Pacino"
    },
    "sendDeltaEmail": true,
    "emailContent": {
        "deltaSummary": "<h3>My custom HTML for the edit email</h3>",
        "packageDetails": "<h3>My Custom HTML for the approver notification email</h3>"
    }
}

json

{
    "entry['number_field_natural_key']": [
        "validation.notFound"
    ],
    "entry['text_field_natural_key']": [
        "validation.required"
    ],
    "entry['person_field_natural_key']": [
        "validation.badAnswerType"
    ],
    "entry['office_field_natural_key']": [
        "validation.notFound"
    ],
    "entry['not_known']": [
        "validation.invalidValue"
    ]
}

List Package Comments

Get a list of all comments for an existing package.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/comments

Example

RequestSucccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/25/packages/12345678/comments

json

[
    {
        "approversOnly": false,
        "canDelete": false,
        "comment": "Call Mr. Plow. That's my name. That name again, it's Mr. Plow.",
        "createdAt": "2025-04-30T11:47:03",
        "id": 11111,
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "state": "ACTIVE"
    },
    {
        "approversOnly": false,
        "canDelete": false,
        "comment": "This comment has been removed",
        "createdAt": "2025-04-30T10:47:16",
        "id": 22222,
        "person": {
            "id": 9,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": null,
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": null,
            "officePhone": null
        },
        "state": "INACTIVE"
    }
]

List Attachment Types

Get a list of all attachment types defined for a specified package. This endpoint returns the Attachment Type ID that is required to upload an attachment to the package.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/attachments/types

Key Response Body Parameters

id - The ID of a specific attachment type that you've configured in your form. This value is required to upload an attachment to the package.

visiblePreRouting - Indicates whether an initiator can upload the attachment before routing begins.

requiredPreRouting - Indicates whether an initiator is required to upload the attachment before routing begins.

requiredBeforeComplete - Indicates whether the attachment is required to be uploaded before routing is complete.

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/25/packages/12345678/attachments/types

json

[
    {
        "id": 26,
        "naturalKey": "Confirmation",
        "visiblePreRouting": false,
        "requiredPreRouting": false,
        "requiredBeforeComplete": false,
        "title": "Confirmation",
        "mimeTypeRestrictions": {
            "pdf": false
        }
    },
    {
        "id": 27,
        "naturalKey": "pdf",
        "visiblePreRouting": true,
        "requiredPreRouting": false,
        "requiredBeforeComplete": false,
        "title": "PDF",
        "mimeTypeRestrictions": {
            "pdf": true
        }
    },
    {
        "id": 25,
        "naturalKey": "Transcripts",
        "visiblePreRouting": true,
        "requiredPreRouting": false,
        "requiredBeforeComplete": false,
        "title": "Transcripts",
        "mimeTypeRestrictions": {
            "pdf": false
        }
    }
]

Upload Attachment to Package

Upload an attachment to an existing package.

Request URL

http

POST /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/attachments/types/{attachmentTypeId}

Request Parameters

attachmentTypeId - The id of the attachment type retrieved from List Attachment Types

Request Body

Using a multipart/form-data POST

name="file" - The content of the file that is being uploaded.

name="description" - The description of the attachment. This is optional and can be omitted.

Example

RequestMulti-part formatSuccess Response

http

POST https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/25/packages/12345678/attachments/types/26

http

--93dd69d3-81ab-4cb8-955a-d5741cdea68c
Content-Disposition: form-data; name="file"; filename="test_attachment1.txt"
Content-Type: application/pdf


--93dd69d3-81ab-4cb8-955a-d5741cdea68c
Content-Disposition: form-data; name="description"

This is the description of the file

--93dd69d3-81ab-4cb8-955a-d5741cdea68c--

json

{
    "id": 6,
    "fileName": "Confirmation.txt",
    "description": "description #1",
    "attachmentType": {
        "id": 26,
        "naturalKey": "Confirmation",
        "visiblePreRouting": false,
        "requiredPreRouting": false,
        "requiredBeforeComplete": false,
        "title": "Confirmation",
        "mimeTypeRestrictions": {
            "pdf": false
        }
    },
    "person": {
        "id": 304,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": "Application Developer",
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": "2900 UCC",
        "officePhone": "319-123-1234",
        "naturalKey": null,
        "type": "idw",
        "hawkid": "rbriggs"
    },
    "fileSize": 40,
    "uploadTimestamp": "2016-03-09T10:29:55"
}

List of Uploaded Attachments

Get a list of all attachments uploaded to an existing package.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/attachments

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/25/packages/12345678/attachments

json

[
    {
        "id": 3,
        "fileName": "Confirmation.pdf",
        "description": "description #1",
        "attachmentType": {
            "id": 26,
            "naturalKey": "Confirmation",
            "visiblePreRouting": false,
            "requiredPreRouting": false,
            "requiredBeforeComplete": false,
            "title": "Confirmation",
            "mimeTypeRestrictions": {
                "pdf": false
            }
        },
        "person": {
            "id": 304,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": "Application Developer",
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": "2900 UCC",
            "officePhone": "319-123-1234",
            "naturalKey": null,
            "type": "idw",
            "hawkid": "rbriggs"
        },
        "fileSize": 644338,
        "uploadTimestamp": "2016-03-09T10:29:54"
    },
    {
        "id": 4,
        "fileName": "Confirmation.pdf",
        "description": "description #1",
        "attachmentType": {
            "id": 26,
            "naturalKey": "Confirmation",
            "visiblePreRouting": false,
            "requiredPreRouting": false,
            "requiredBeforeComplete": false,
            "title": "Confirmation",
            "mimeTypeRestrictions": {
                "pdf": false
            }
        },
        "person": {
            "id": 304,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": "Application Developer",
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": "2900 UCC",
            "officePhone": "319-123-1234",
            "naturalKey": null,
            "type": "idw",
            "hawkid": "rbriggs"
        },
        "fileSize": 644338,
        "uploadTimestamp": "2016-03-09T10:29:54"
    },
    {
        "id": 5,
        "fileName": "Confirmation.pdf",
        "description": "description #1",
        "attachmentType": {
            "id": 26,
            "naturalKey": "Confirmation",
            "visiblePreRouting": false,
            "requiredPreRouting": false,
            "requiredBeforeComplete": false,
            "title": "Confirmation",
            "mimeTypeRestrictions": {
                "pdf": false
            }
        },
        "person": {
            "id": 304,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": "Application Developer",
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": "2900 UCC",
            "officePhone": "319-123-1234",
            "naturalKey": null,
            "type": "idw",
            "hawkid": "rbriggs"
        },
        "fileSize": 644338,
        "uploadTimestamp": "2016-03-09T10:29:54"
    },
    {
        "id": 6,
        "fileName": "Confirmation.txt",
        "description": "description #1",
        "attachmentType": {
            "id": 26,
            "naturalKey": "Confirmation",
            "visiblePreRouting": false,
            "requiredPreRouting": false,
            "requiredBeforeComplete": false,
            "title": "Confirmation",
            "mimeTypeRestrictions": {
                "pdf": false
            }
        },
        "person": {
            "id": 304,
            "displayName": "Simpson, Homer J",
            "hrdeptdesc": null,
            "collegeName": null,
            "personType": null,
            "title": "Application Developer",
            "univid": "00028152",
            "email": "homer-j-simpson@uiowa.edu",
            "campusPostalAddress": "2900 UCC",
            "officePhone": "319-123-1234",
            "naturalKey": null,
            "type": "idw",
            "hawkid": "rbriggs"
        },
        "fileSize": 40,
        "uploadTimestamp": "2016-03-09T10:29:55"
    }
]

Download an Attachment

Download an attachment uploaded to a package.

Request URL

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/{packageId}/attachments/{attachmentId}

Request Parameters

attachmentId - The id of the uploaded attachment

Example

RequestSuccess Headers

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/25/packages/12345678/attachments/3

http

Date: Wed, 09 Mar 2016 16:29:55 GMT
Content-Length: 644338
Content-Disposition: inline; filename="Confirmation.pdf"
Content-Type: application/pdf
Cache-Control: no-cache

Api Client Routing Tools

Security & Access

The endpoints in this section do not verify the user has any rights with the specified package. It is your application's responsibility to verify the user you are making the call on behalf of has the rights to call this endpoint for the specified package.

Get Package Status in Bulk

Get the current status of packages in bulk.

Request URL

Multiple packageIds can be passed.

http

GET /workflow/{env}/api/developer/forms/{formId}/packages/status?id={packageId1}&id={packageId2}

Example

RequestSuccess Response

http

GET https://apps.its.uiowa.edu/workflow/prod/api/developer/forms/1/packages/status?id=13&id=14&id=15&id=16

json

[
    {
        "id": 16,
        "state": "PRE_ROUTING"
    },
    {
        "id": 15,
        "state": "ROUTING"
    },
    {
        "id": 14,
        "state": "VOID"
    },
    {
        "id": 13,
        "state": "COMPLETE"
    }
]

Api Version 1.2 example

This endpoint supports an additional version which is requested via the accept header. Version 1.2 simply returns additional signature information including the name, status, and permission level of current approvers. The office which owns the routing that resulted in this signature is also provided. This will either be the office that the package is currently routing through in the case of an office destination or the office that owns the form for all other destinations.

RequestSuccess Response

http

Accept: application/vnd.workflow+json;version=1.2

GET /workflow/prod/api/developer/forms/1/packages/status?id=8&id=9&id=10

json

[
    {
        "id": 8,
        "state": "COMPLETE",
        "inboxSignatures": []
    },
    {
        "id": 9,
        "state": "ROUTING",
        "inboxSignatures": [
            {
                "id": 6,
                "approver": "Simpson, Homer J",
                "state": "RECEIVED",
                "permission": "SIGNATURE_REQUIRED",
                "responsibleOffice": {
                    "id": 46,
                    "name": "Office 1",
                    "naturalKey": "office_1"
                }
            }
        ]
    },
    {
        "id": 10,
        "state": "ROUTING",
        "inboxSignatures": [
            {
                "id": 4,
                "approver": "Simpson, Homer J",
                "state": "RECEIVED",
                "permission": "SIGNATURE_REQUIRED",
                "responsibleOffice": {
                    "id": 47,
                    "name": "Office 2",
                    "naturalKey": "office_2"
                }
            },
            {
                "id": 5,
                "approver": "Flanders, Ned",
                "state": "RECEIVED",
                "permission": "SIGNATURE_REQUIRED",
                "responsibleOffice": {
                    "id": 47,
                    "name": "Office 2",
                    "naturalKey": "office_2"
                }
            }
        ]
    }
]

Void Package Routing

Void a package so that it is no longer routing.

Request URL

http

PUT https://apps.its.uiowa.edu/workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}

Request Body

id - The package_id to void

state - Must be set to "VOID"

voidReason - The reason for the void. Must be one of the following: "DUPLICATE_TRANSACTION", "INCORRECT_FORM", " TRANSACTION_CANCELLED", "TRANSACTION_DENIED"

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/5

{
  "id" : 5,
  "state" : "VOID",
  "voidReason" : "TRANSACTION_CANCELLED"
}

json

{
    "id": 5,
    "state": "VOID",
    "voidReason": "TRANSACTION_CANCELLED",
    "actions": {
        "canView": true,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 5,
        "signatureId": null
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:40",
    "actionDate": "2015-04-20T16:46:40",
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Unvoid Package Routing

Unvoid a package that is currently in a VOID sate and return it to its former state before it was voided. If you void a ROUTING package and then unvoid it, it will return to the ROUTING state. If you void a COMPLETE package and then unvoid it, it will return to the COMPLETE state.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/unvoid

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/6/unvoid

json

{
    "id": 6,
    "state": "ROUTING",
    "voidReason": "TRANSACTION_DENIED",
    "actions": {
        "canView": false,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 6,
        "signatureId": null
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:41",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Restart Package Routing

Restart the routing of a package and require all approvers to re-sign the package.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/restart

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/4/restart

json

{
    "id": 4,
    "state": "ROUTING",
    "voidReason": null,
    "actions": {
        "canView": false,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 4,
        "signatureId": null
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:40",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Return Package to Routing

Return a package with a COMPLETE state to routing. It will be placed in a specified user's inbox at the end of the route. Once it is signed by that user, the package will return to a COMPLETE state.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/return

Request Body

univid - The University ID of the user who will receive the package in their inbox.

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/7/return

{
  "univid" : 00027147  
}

json

{
    "id": 7,
    "state": "ROUTING",
    "voidReason": null,
    "actions": {
        "canView": true,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 7,
        "signatureId": null
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:41",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00027147",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Remove Package from Routing

Update the specified package state to PRE_ROUTING. This effectively removes the package from Workflow as it will not show up in anyone's inbox or history. Authorized users are still able to search the package (via Package Management Tools) and see the full routing history of the package if they need to.

A package that is removed from Workflow can be returned in two ways:

Use the Start Routing an Existing Package endpoint. This can only be used by the original initiator.
Use the Re-Initiate Package Routing endpoint.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/remove

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/8/remove

json

{
    "id": 8,
    "state": "PRE_ROUTING",
    "voidReason": null,
    "actions": {
        "canView": false,
        "canEdit": false,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canAddApprover": false,
        "canVoidAfter": false,
        "packageId": 8,
        "signatureId": null
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:42",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Re-Initiate Package Routing

Start routing a package that was previously removed from Workflow.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/re_initiate

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/9/re_initiate

json

{
    "id": 9,
    "state": "ROUTING",
    "voidReason": null,
    "actions": {
        "canView": true,
        "canEdit": true,
        "canSign": true,
        "canVoid": true,
        "canInitiatorVoid": false,
        "canAddApprover": true,
        "canVoidAfter": false,
        "packageId": 9,
        "signatureId": 20
    },
    "subType": null,
    "emailContent": {
        "packageDetails": null
    },
    "routingDate": "2015-04-20T16:46:43",
    "actionDate": null,
    "initiator": {
        "id": 9,
        "displayName": "Simpson, Homer J",
        "hrdeptdesc": null,
        "collegeName": null,
        "personType": null,
        "title": null,
        "univid": "00028152",
        "email": "homer-j-simpson@uiowa.edu",
        "campusPostalAddress": null,
        "officePhone": null
    },
    "commentCount": 0,
    "attachmentCount": 0
}

Return to Initiator

Allows developers to send the package back to the initiator. The package will be sent to the initiator and placed in a draft state. The initiator must resubmit and all approvers must re-approve it.

Request URL

http

PUT /workflow/{env}/api/developer/tools/forms/{formId}/packages/{packageId}/returnToInitiator

Request Body

comment - The comment / reason the package is being returned to the initiator. This comment will be emailed to the initiator and will appear in the widget.

Example

RequestSuccess Response

http

PUT https://apps.its.uiowa.edu/workflow/prod/api/developer/tools/forms/1/packages/9/returnToInitiator

{
  "comment" : "This is the comment sent to the initiator" 
}

json

{
    "id": 9,
    "state": "DRAFT",
    "voidReason": null,
    "subType": "Employee",
    "routingDate": "2024-05-28T11:40:58",
    "actionDate": null,
    "initiator": {
        "id": 52651,
        "displayName": "Doe, John",
        "hrdeptdesc": "ITS-Admin Information Systems",
        "personType": "Faculty/Staff",
        "title": "Senior Application Developer",
        "univid": "00012345",
        "email": "john-doe@uiowa.edu",
        "campusPostalAddress": "100 UCC",
        "officePhone": "+1 319 555 5500",
        "jobCode": "PIA3",
        "naturalKey": null,
        "hawkid": "jdoe",
        "directoryRestricted": false,
        "activeUser": true
    },
    "commentCount": 0,
    "attachmentCount": 0,
    "emailContent": {
        "packageDetails": null
    },
    "actions": {
        "canView": true,
        "canEdit": true,
        "canSign": false,
        "canVoid": false,
        "canInitiatorVoid": false,
        "canVoidAfter": false,
        "canAddApprover": false,
        "packageId": 9,
        "signatureId": null
    }
}

Office Search

Get a list of offices matching a particular office key.

Request URL

http

GET     /workflow/api/v2/search/offices/flat?searchTerm={key}

Request Parameters

searchTerm - The office natural key you are searching for

Example

RequestSuccess Response

http

GET /workflow/prod/api/offices?key=43-5064

json

[
    {
        "id": 5549,
        "lastSynced": "2025-05-14T05:15:00",
        "name": "ITS Admin Information Systems",
        "naturalKey": "43-5064",
        "scopeNaturalKey": "department",
        "state": "IMPORTED"
    },
    {
        "id": 12406,
        "lastSynced": "2025-05-14T05:15:00",
        "name": "ITS Admin Information Systems Subdepartment",
        "naturalKey": "43-5064-00000",
        "scopeNaturalKey": "sub_department",
        "state": "IMPORTED"
    },
    {
        "id": 10139,
        "lastSynced": "2025-05-14T05:15:00",
        "name": "ITS Admin Information Systems",
        "naturalKey": "43-5064-40100",
        "scopeNaturalKey": "sub_department",
        "state": "IMPORTED"
    },
    {
        "id": 22799,
        "lastSynced": null,
        "name": "billing Sub Department",
        "naturalKey": "43-5064-billing",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 15716,
        "lastSynced": null,
        "name": "Campus Data Sub Department",
        "naturalKey": "43-5064-campus_data",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 28729,
        "lastSynced": null,
        "name": "DAI",
        "naturalKey": "43-5064-dai",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 21906,
        "lastSynced": null,
        "name": "financials Sub Department",
        "naturalKey": "43-5064-financials",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 14715,
        "lastSynced": null,
        "name": "Identity and Access Management",
        "naturalKey": "43-5064-iam",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 18887,
        "lastSynced": null,
        "name": "students Sub Department",
        "naturalKey": "43-5064-students",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    },
    {
        "id": 20744,
        "lastSynced": null,
        "name": "UEW Sub Department",
        "naturalKey": "43-5064-uew",
        "scopeNaturalKey": "sub_department",
        "state": "CREATED"
    }
]

Workflow API ​

Authentication and Authorization NEW ​

Authentication ​

Authorization ​

Common Parameters ​

Create a Package ​

Route an Existing Package ​

Get Basic Package Information ​

Download a Package PDF ​

Get Package History ​

Get User's Allowed Package Actions ​

Get Package Entry Data ​

Update Package Entry Data ​

List Package Comments ​

List Attachment Types ​

Upload Attachment to Package ​

List of Uploaded Attachments ​

Download an Attachment ​

Api Client Routing Tools ​

Get Package Status in Bulk ​

Void Package Routing ​

Unvoid Package Routing ​

Restart Package Routing ​

Return Package to Routing ​

Remove Package from Routing ​

Re-Initiate Package Routing ​

Return to Initiator ​

Office Search ​

Workflow API

Authentication and Authorization NEW

Authentication

Authorization

Common Parameters

Create a Package

Route an Existing Package

Get Basic Package Information

Download a Package PDF

Get Package History

Get User's Allowed Package Actions

Get Package Entry Data

Update Package Entry Data

List Package Comments

List Attachment Types

Upload Attachment to Package

List of Uploaded Attachments

Download an Attachment

Api Client Routing Tools

Get Package Status in Bulk

Void Package Routing

Unvoid Package Routing

Restart Package Routing

Return Package to Routing

Remove Package from Routing

Re-Initiate Package Routing

Return to Initiator

Office Search