Workflows

A Workflow represents the stages of an automation that, in its simplest form, transform source data into output documents.

Fields

Field	Type	Editable	Description
id	String	false	The unique ID of the workflow. Used to reference the workflow in all requests.
name	String	true	The name of the workflow.
color	String	true	The colour of the workflow icon in Portant Workflow as a hex string, prefixed with #.
icon	String	true	The name of the icon used in Portant Workflow.
status	String	false	The current status of the workflow. One of: - "COMPLETE": the workflow is runnable. - "INCOMPLETE": the workflow needs more configuration before it can run. - "ARCHIVED": the workflow is no longer usable.
autoCreate	Boolean	false	When true, the workflow listens for source events and creates a new automation each time one arrives.
owner	Owner	false	The owner of this workflow.
team	Team	false	The team this workflow belongs to.
source	Source	false	The source of data for this workflow.
documents	Document	false	The template documents for this workflow.
outgoingWebhook	Outgoing Webhook	false	The outgoing webhook of this workflow, used to listen for automation events.
createdByApi	Boolean	false	True when the workflow was created via the Developer API.
createdAt	String	false	An ISO 8601 timestamp for when the workflow was created.
updatedAt	String	false	An ISO 8601 timestamp for when the workflow was last updated.

Example

```json
{
    "id": "wkf_kGQK9PBWDT1JCr",
    "name": "Invoice Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "COMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_DsH4TGYXs4XPpB",
        "name": "Blake Lockley",
        "email": "blake@portant.co"
    },
    "team": null,
    "source": {
        "id": "src_NZHJYjlgrvklHb",
        "sourceType": "WEBHOOK",
        "sourceFields": [
            "Order Number",
            "LineItem.Name",
            "LineItem.Price",
        ],
        "webhookUrl": "https://webhooks.portant.co/50c7912b14c7acbe9df32521ec60a27c"
    },
    "documents": [
        {
            "id": "doc_5LGGqC5S78RNS0",
            "documentType": "GOOGLE_DOCS",
            "file": {
                "id": "1uNfBHAKhcgRsiftb7xRpTJRS0k9LY1iX1gUnTOE0zU4",
                "name": "Complete Workflow Please - [Template]",
                "url": "https://docs.google.com/document/d/1uNfBHAKhcgRsiftb7xRpTJRS0k9LY1iX1gUnTOE0zU4/edit?usp=drivesdk",
                "mimeType": "application/vnd.google-apps.document"
            },
            "outputName": "Document for {{First Name}}",
            "pdfPassword": "jeRe/\/\eyWaZH3re",
            "enablePdfPassword": true,
            "enablePdfPreventCopy": false,
            "previewUrl": "https://preview.portant.co/doc_5LGGqC5S78RNS0"
        }
    ],
    "outgoingWebhook": {
        "id": "owc_XY1Ys4gqrpX8cp",
        "webhookUrl": "https://webhook.site/d22c56ab-40ac-4f9a-93ef-02520235c0da"
    },
    "createdByApi": true,
    "createdAt": "2024-08-12T16:20:44.346666+10:00",
    "updatedAt": "2024-08-12T16:20:48.408357+10:00"
}
```

Endpoints

List all workflows

GET /workflows/

Return every Workflow owned by, or shared with, the team of the API user.

Responses

Status	Body
200 OK	Array<Workflow>
403 Unauthorised	Error

Create a workflow

POST /workflows/

Create a new workflow.

Request

A partial Workflow object as JSON. The only required field is name.

{
    name: "A simple workflow"
}

You can also create a complete workflow in one POST by including the optional subcomponents and their required fields.

Fields suffixed with ? are optional.

{
    name: "A complete Workflow from Scratch",
    color?: "#...",
    icon?: "...",
    source?: {
        "sourceFields": ["Field Name 1", "Field Name 2"]
    },
    document?: {
        fileId: "<google file id>"
    },
    outgoingWebhook?: {
        webhookUrl: "<webhook url for event listening>"
    }
}

Responses

Status	Body
201 Created	Workflow
400 Bad Request	Error
403 Unauthorised	Error

Retrieve a workflow

GET /workflows/<wkf_id>/

Retrieve a specific workflow by ID.

Responses

Status	Body
200 OK	Workflow
403 Unauthorised	Error
404 Not Found	Error

Update a workflow

PATCH /workflows/<wkf_id>/

Update a specific workflow by ID.

Request

A partial Workflow object as JSON. Fields suffixed with ? are optional.

{
    name?: "...",
    color?: "#...",
    icon?: "..."
 }

Response

Status	Body
200 OK	Workflow
400 Bad Request	Error
403 Unauthorised	Error
404 Not Found	Error

Delete a workflow

DELETE /workflows/<wkf_id>/

Delete a specific workflow by ID. The workflow isn't actually deleted; its status is set to "ARCHIVED". Archived workflows can be restored by contacting the customer success team.

Response

Status	Body
204 No Content
400 Bad Request	Error
403 Unauthorised	Error
404 Not Found	Error