Skip to main content
Kinetic Community

Submissions

A submission represents an instance of a form that contains field values.

Operation List

GET /kapps/{kappSlug}/forms/{formSlug}/submissions Retrieve Submissions for a Form
GET /kapps/{kappSlug}/submissions Retrieve Submissions by Kapp
GET /kapps/{kappSlug}/submissions?type={type} Retrieve Submissions by Type
GET /submissions/{submissionId} Retrieve a Submission
GET /submissions/{submissionId}/files/{fieldName}/{fileIndex}/{fileName}/url Retrieve the download URL for an attachment in a File field.
POST /kapps/{kappSlug}/forms/{formSlug}/submissions Create/Submit new Submission
POST /kapps/{kappSlug}/forms/{formSlug}/submissions?page={pageName} Submit page of new Submission
POST /submissions/{submissionId}?page={pageName} Submit page of existing Submission
PUT /submissions/{submissionId} Update a Submission
PATCH /kapps/{kappSlug}/forms/{formSlug}/submissions Patch new Submission
PATCH /submissions/{submissionId} Patch existing Submission
DELETE /submissions/{submissionId} Delete a Submission

Resource Schema

Available Includes

  • details
  • children
  • descendents
  • form
  • origin
  • parent
  • type
  • values

Operations

Retrieve Submissions for a Form

GET /kapps/{kappSlug}/forms/{formSlug}/submissions

Returns submissions for the specified Form.

Request

Path Parameters
kappSlug

The slug of the Kapp that the form belongs to.

formSlug

The slug of the Form that the submissions belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

coreState

Searches for submissions that have a core state that matches this parameter.

If no value is provided, the results will contain submissions in all core states.

timeline

Date property to search by.

The default value is createdAt.

direction

Result Set sorting direction. The default value is descending.

start

Start date/time of the timeline.

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

end

End date/time of the timeline).

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

limit

Limit the number of results returned. If not provided, the server will limit the results to 25 submissions.

The default limit is 25.

Maximum: 1000

pageToken

The value to use as the offset for the page of submissions to return. The submission that matches this value will not be included in the results.

q

A custom qualification that can be constructed similar to a SQL where clause that allows building complex expressions using logical and relational operators against submission properties and field values.

Operators:

AND             Returns boolean true if and only if both expressions are true
                Example:    expression1 AND expression2

OR              Returns boolean true if at least one expression is true
                Example:    expression1 OR expression1

IN              Returns boolean true if the key matches one of the list values
                Example:    key IN ("Value One", "Value Two", "Value Three")

=               Returns boolean true if the key is exactly equal to the value
                Example:    key = "Test Value"

Expression Symbols:

null            Means no value
                Example:    key = null

(               Left parentheses for logic grouping, MUST be used with right parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

)               Right parentheses for logic grouping, MUST be used with left parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

,               Comma for separating list items
                Example:    key IN ("Value 1", "Value 2")

Submission Properties:

closedBy        Username that closed the submission

createdBy       Username that created the submission

sessionToken    Used for anonymous submissions

submittedBy     Username that submitted the submission

updatedBy       Username that last updated the submission

values          Any field that is implemented by the Form.
                Example: the field named 'Approver' would be referred as:  values[Approver]

Example Qualification:

(values[Requested By] = "john.doe" OR values[Requested For] = "john.doe") 
    AND values[Status] IN ("Pending Assignment", "On Hold")

Response

Body
{
  "submissions": [
    {
      "id": "",
      "coreState": "Draft",
      "currentPage": null,
      "label": "${id}",
      "type": "Service",
      "children": [],
      "descendents": [],
      "form": "",
      "origin": null,
      "parent": null,
      "values": {}
    }
  ]
}

Retrieve Submissions by Kapp

GET /kapps/{kappSlug}/submissions

Returns submissions for the specified Kapp.

Request

Path Parameters
kappSlug

The slug of the Kapp that the submission belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

coreState

Searches for submissions that have a core state that matches this parameter.

If no value is provided, the results will contain submissions in all core states.

timeline

Date property to search by.

The default value is createdAt.

direction

Result Set sorting direction. The default value is descending.

start

Start date/time of the timeline.

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

end

End date/time of the timeline).

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

limit

Limit the number of results returned. If not provided, the server will limit the results to 25 submissions.

The default limit is 25.

Maximum: 1000

pageToken

The value to use as the offset for the page of submissions to return. The submission that matches this value will not be included in the results.

q

A custom qualification that can be constructed similar to a SQL where clause that allows building complex expressions using logical and relational operators against submission properties and field values.

Operators:

AND             Returns boolean true if and only if both expressions are true
                Example:    expression1 AND expression2

OR              Returns boolean true if at least one expression is true
                Example:    expression1 OR expression1

IN              Returns boolean true if the key matches one of the list values
                Example:    key IN ("Value One", "Value Two", "Value Three")

=               Returns boolean true if the key is exactly equal to the value
                Example:    key = "Test Value"

Expression Symbols:

null            Means no value
                Example:    key = null

(               Left parentheses for logic grouping, MUST be used with right parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

)               Right parentheses for logic grouping, MUST be used with left parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

,               Comma for separating list items
                Example:    key IN ("Value 1", "Value 2")

Submission Properties:

closedBy        Username that closed the submission

createdBy       Username that created the submission

sessionToken    Used for anonymous submissions

submittedBy     Username that submitted the submission

updatedBy       Username that last updated the submission

values          Any field that is implemented by the Form.
                Example: the field named 'Approver' would be referred as:  values[Approver]

Example Qualification:

(values[Requested By] = "john.doe" OR values[Requested For] = "john.doe") 
    AND values[Status] IN ("Pending Assignment", "On Hold")

Response

Body
{
  "submissions": [
    {
      "id": "",
      "coreState": "Draft",
      "currentPage": null,
      "label": "${id}",
      "type": "Service",
      "children": [],
      "descendents": [],
      "form": "",
      "origin": null,
      "parent": null,
      "values": {}
    }
  ]
}

Retrieve Submissions by Type

GET /kapps/{kappSlug}/submissions?type={type}

Returns submissions for the specified Kapp that are of the specified type.

Request

Path Parameters
kappSlug

The slug of the Kapp that the submission belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

type

The type of submissions to retrieve. Form types are defined by each Kapp, and may be different between Kapps.

Examples:

  • Approval
  • Console
  • Content
  • Service
  • Service Description
  • Subservice
  • Template
  • Work Order
coreState

Searches for submissions that have a core state that matches this parameter.

If no value is provided, the results will contain submissions in all core states.

timeline

Date property to search by.

The default value is createdAt.

direction

Result Set sorting direction. The default value is descending.

start

Start date/time of the timeline.

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

end

End date/time of the timeline).

This value should be used to both refine and limit the search results.

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

limit

Limit the number of results returned. If not provided, the server will limit the results to 25 submissions.

The default limit is 25.

Maximum: 1000

pageToken

The value to use as the offset for the page of submissions to return. The submission that matches this value will not be included in the results.

q

A custom qualification that can be constructed similar to a SQL where clause that allows building complex expressions using logical and relational operators against submission properties and field values.

Operators:

AND             Returns boolean true if and only if both expressions are true
                Example:    expression1 AND expression2

OR              Returns boolean true if at least one expression is true
                Example:    expression1 OR expression1

IN              Returns boolean true if the key matches one of the list values
                Example:    key IN ("Value One", "Value Two", "Value Three")

=               Returns boolean true if the key is exactly equal to the value
                Example:    key = "Test Value"

Expression Symbols:

null            Means no value
                Example:    key = null

(               Left parentheses for logic grouping, MUST be used with right parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

)               Right parentheses for logic grouping, MUST be used with left parentheses
                Example:    (key = "Value 1" OR key = "Value 2")

,               Comma for separating list items
                Example:    key IN ("Value 1", "Value 2")

Submission Properties:

closedBy        Username that closed the submission

createdBy       Username that created the submission

sessionToken    Used for anonymous submissions

submittedBy     Username that submitted the submission

updatedBy       Username that last updated the submission

values          Any field that is implemented by the Form.
                Example: the field named 'Approver' would be referred as:  values[Approver]

Example Qualification:

(values[Requested By] = "john.doe" OR values[Requested For] = "john.doe") 
    AND values[Status] IN ("Pending Assignment", "On Hold")

Response

Body
{
  "submissions": [
    {
      "id": "",
      "coreState": "Draft",
      "currentPage": null,
      "label": "${id}",
      "type": "Service",
      "children": [],
      "descendents": [],
      "form": "",
      "origin": null,
      "parent": null,
      "values": {}
    }
  ]
}

Retrieve a Submission

GET /submissions/{submissionId}

Returns information about a single Submission.

Request

Path Parameters
submissionId

The id of the submission.

Query Parameters
include

comma-separated list of properties to include in the response

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Retrieve the download URL for an attachment in a File field.

GET/submissions/{submissionId}/files/{fieldName}/{fileIndex}/{fileName}/url

Returns the URL to download the attachment for a File field. The URL is valid for 5 seconds.

Request

Path Parameters
submissionId

The id of the submission.

fieldName

Name of the field the file attachment was submitted for.

fileIndex

The index in the array of attachments for the field. This value will always be 0 for File fields that only allow a single value.

fileName

Name of the file that was attached to the field.

Response

Body
{
  "url": "http://..."
}

Create/Submit new Submission

POST /kapps/{kappSlug}/forms/{formSlug}/submissions

Creates/submits a new submission. All properties in the request body are optional, and only the properties supplied will be created. Field values will be validated, and webhooks will be executed if necessary.

Request

Path Parameters
kappSlug

The slug of the Kapp that the form belongs to.

formSlug

The slug of the Form that the submissions belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

completed

signals that the submission should be completed (equivalent of submitting all of the pages at once)

The default value is false.

Body
{
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Submit page of new Submission

POST /kapps/{kappSlug}/forms/{formSlug}/submissions?page={pageName}

Creates a new submission for the specified form.

The request body requires a ‘values’ property that is a map of the specified page’s field names to values.

Only fields from the specified page may be submitted with this API method.

Request

Path Parameters
kappSlug

The slug of the Kapp that the form belongs to.

formSlug

The slug of the Form that the submissions belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

page

The URI encoded name of the Page being submitted.

staged

Indicates whether field validations and page advancement should take place.

The default value is false.

defer

Indicates the submission is for a subform embedded in a parent submission.

The default value is true.

Body
{
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Submit page of existing Submission

POST /submissions/{submissionId}?page={pageName}

Submits field values for an existing submission for the specified page.

The request body requires a ‘values’ property that is a map of the specified page’s field names to values.

Only fields from the specified page may be submitted with this API method.

Request

Path Parameters
submissionId

The id of the submission.

Query Parameters
include

comma-separated list of properties to include in the response

page

The URI encoded name of the Page being submitted.

staged

Indicates whether field validations and page advancement should take place.

The default value is false.

defer

Indicates the submission is for a subform embedded in a parent submission.

The default value is true.

Body
{
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Update a Submission

PUT /submissions/{submissionId}

Updates an existing submission.

All properties in the request body are optional, and only the properties supplied will be updated. Field values will be validated, the core state conditions will be evaluated, and webhooks will be executed if necessary.

Request

Path Parameters
submissionId

The id of the submission.

Query Parameters
include

comma-separated list of properties to include in the response

Body
{
  "coreState": "Draft",
  "currentPage": null,
  "type": "Service",
  "origin": null,
  "parent": null,
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Patch new Submission

PATCH /kapps/{kappSlug}/forms/{formSlug}/submissions

Patches a new submission for the specified form. All properties in the request body are optional, and only the properties supplied will be patched. Unlike an update, a patch does not trigger any field validations, evaluate core state conditions, or execute any webhooks.

Request

Path Parameters
kappSlug

The slug of the Kapp that the form belongs to.

formSlug

The slug of the Form that the submissions belongs to.

Query Parameters
include

comma-separated list of properties to include in the response

Body
{
  "coreState": "Draft",
  "currentPage": null,
  "type": "Service",
  "origin": null,
  "parent": null,
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Patch existing Submission

PATCH /submissions/{submissionId}

Patches an existing Submission.

All properties in the request body are optional, and only the properties supplied will be patched. Unlike an update, a patch does not trigger any field validation, evaluate core state conditions, or execute any webhooks.

Request

Path Parameters
submissionId

The id of the submission.

Query Parameters
include

comma-separated list of properties to include in the response

Body
{
  "coreState": "Draft",
  "currentPage": null,
  "type": "Service",
  "origin": null,
  "parent": null,
  "values": {}
}

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}

Delete a Submission

DELETE /submissions/{submissionId}

Deletes a submission.

Submissions may only be deleted if the form Submission Modification security policy (or the kapp Default Submission Modification security policy if the form Submission Modification security policy is not set) evaluates to true and only if the request is being made by a Kapp Admin or if the submission is in the Draft core state.

Request

Path Parameters
submissionId

The id of the submission.

Query Parameters
include

comma-separated list of properties to include in the response

Response

Body
{
  "submission": {
    "id": "",
    "coreState": "Draft",
    "currentPage": null,
    "label": "${id}",
    "type": "Service",
    "children": [],
    "descendents": [],
    "form": "",
    "origin": null,
    "parent": null,
    "values": {}
  }
}