Portant Docs
Homepage Install in HubSpot Start for free

Workflow Automation Items

Automation items are what is produced from a workflow. They can be considered "outputs" of an automation/workflow but we use the terminology of "items" as they contain multiple child objects, some such being the actual document "output" itself.

Endpoints

List a workflow's items

GET /workflows/<workflow_id>/items/

Return the automation items of a specific workflow, newest first. Results are paginated with 20 items per page.

curl --location --request GET 'https://api.portant.co/v0/workflows/<workflow_id>/items/?page=1' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

Path Parameters

Parameter Type Required Description
workflow_id String true The id of the workflow which you are requesting automation items for.

Query Parameters

Parameter Type Required Description
page Number false The page of results to return, starting at 1. Defaults to 1.

Response Body

Field Type Description
results Array Up to 20 automation items for the requested page.
total Number The total number of automation items in the workflow, across all pages. 
{
    "results": [
        { "id": "aui_3hKd92LmQpZx1A", "...": "..." }
    ],
    "total": 57
}

To fetch every item, keep incrementing page until you have collected total items.

Responses

Status Body
200 OK { results: Array, total: Number }
403 Unauthorised Error
404 Not Found Error (the workflow does not exist, or page is out of range)

Fields

Workflow Automation Item

Field Type Editable Description
id String false The unique ID of the automation item, prefixed with aui_.
status String false The overall status of the item. One of: - "PENDING": the item is still being processed. - "COMPLETED": the item finished successfully. - "COMPLETED_WITH_ERROR": the item finished, but an error occurred. - "COMPLETED_PARTIALLY": the item finished, but some of its steps did not. - "CANCELLED": the item was cancelled before it finished.
stage String false The step of the workflow the item is currently at. One of: "INITIAL", "OUTPUT", "SIGNATURES_DRAFT", "EMAIL_DRAFT", "REVIEW_PENDING", "REVIEW_APPROVED", "OUTPUT_POST", "SIGNATURES_REQUEST", "SIGNATURES_PENDING", "SIGNATURES_COMPLETED", "EMAIL", "FINALISED", "REVIEW_REJECTED". The review and signature stages only apply to workflows that include review or signature blocks.
approvedBy String false The ID of the user who approved the item, when the workflow includes a review step. Otherwise null.
approvedAt String false An ISO 8601 timestamp for when the item was approved, or null.
isDeleted Boolean false True when the item has been deleted by a user.
sourceItemNumber String false A user-facing identifier from the source, such as a row number or response number. Can be empty.
sourceItemName String false A user-facing name from the source, such as a HubSpot deal's name. Can be empty.
outputs Array<Output> false The documents generated for this item.
signatureRequests Array<Signature Request> false The signature requests sent for this item, ordered by recipient number.
createdAt String false An ISO 8601 timestamp for when the item was created.
updatedAt String false An ISO 8601 timestamp for when the item was last updated.

Output

Field Type Editable Description
id String false The unique ID of the output, prefixed with out_.
outputName String false The name of the generated document, after merge tags in the workflow's output name are replaced.
file File false The generated document, such as a Google Doc, Sheet or Slides file. null when no file was generated.
filePdf File false The PDF version of the generated document. null when no PDF was generated.
createdAt String false An ISO 8601 timestamp for when the output was created.
updatedAt String false An ISO 8601 timestamp for when the output was last updated.

File

Field Type Editable Description
id String false The Google Drive file ID.
name String false The file name.
url String false A link that opens the file.
mimeType String false The MIME type of the file.
formId String false The Google Form ID, if the file is a Google Form. Otherwise null.
isTrashed Boolean false True when the file has been moved to the trash in Google Drive.
createdAt String false An ISO 8601 timestamp for when Portant first recorded the file.
updatedAt String false An ISO 8601 timestamp for when Portant last updated its record of the file.

Signature Request

Field Type Editable Description
id String false The unique ID of the signature request, prefixed with snr_.
status String false The status of the request. One of: - "PENDING": the request has not been sent yet. - "REQUESTED": the request was sent to the recipient. - "ACCESSED": the recipient opened the request. - "COMPLETED": the recipient signed. - "ERROR": the request could not be sent. - "CANCELED": the request was cancelled. - "EXPIRED": the request expired before it was signed. - "PREVIEW": a preview request, not sent to anyone. - "LINK": a signable link rather than an emailed request.
recipientNumber Number false The position of this recipient in the signing order, starting at 1.
recipientEmail String false The email address of the recipient.
recipientName String false The name of the recipient.
expiry String false An ISO 8601 timestamp for when the request expires, or null if it never expires.
createdAt String false An ISO 8601 timestamp for when the request was created.
updatedAt String false An ISO 8601 timestamp for when the request was last updated.

Example

{
    "id": "aui_3hKd92LmQpZx1A",
    "status": "COMPLETED",
    "stage": "FINALISED",
    "approvedBy": "usr_DsH4TGYXs4XPpB",
    "approvedAt": "2024-08-12T16:25:10.112233+10:00",
    "isDeleted": false,
    "sourceItemNumber": "12",
    "sourceItemName": "Acme Corp Renewal",
    "outputs": [
        {
            "id": "out_7JvP0qWc2Ns8Rt",
            "outputName": "Invoice for Acme Corp",
            "file": {
                "id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdEf",
                "name": "Invoice for Acme Corp",
                "url": "https://docs.google.com/document/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdEf/edit?usp=drivesdk",
                "mimeType": "application/vnd.google-apps.document",
                "formId": null,
                "isTrashed": false,
                "createdAt": "2024-08-12T16:21:02.554411+10:00",
                "updatedAt": "2024-08-12T16:21:02.554411+10:00"
            },
            "filePdf": {
                "id": "1ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210zyxWv",
                "name": "Invoice for Acme Corp.pdf",
                "url": "https://drive.google.com/file/d/1ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210zyxWv/view?usp=drivesdk",
                "mimeType": "application/pdf",
                "formId": null,
                "isTrashed": false,
                "createdAt": "2024-08-12T16:21:05.871002+10:00",
                "updatedAt": "2024-08-12T16:21:05.871002+10:00"
            },
            "createdAt": "2024-08-12T16:21:01.903377+10:00",
            "updatedAt": "2024-08-12T16:21:05.902114+10:00"
        }
    ],
    "signatureRequests": [
        {
            "id": "snr_Qm4Tz8YbHc1Lw0",
            "status": "COMPLETED",
            "recipientNumber": 1,
            "recipientEmail": "jane@acme.com",
            "recipientName": "Jane Smith",
            "expiry": null,
            "createdAt": "2024-08-12T16:25:12.004431+10:00",
            "updatedAt": "2024-08-12T17:02:48.660219+10:00"
        }
    ],
    "createdAt": "2024-08-12T16:20:58.346666+10:00",
    "updatedAt": "2024-08-12T17:02:49.408357+10:00"
}