# Sessions and Workflows

Source: https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/index/

**Beta**

Stage your data, start a workflow against it, and find out when the result is ready.

Two surfaces do this work. A **session** holds the data a product runs against: you stage it, and you can re-stage it as often as you like without starting anything. A **workflow** is one run of a product against that data: it reads what the session holds, runs the product, and produces a result. Staging is free. Starting a workflow is billed, unless your product uses outcome-based billing, where what became of the application decides.

## The whole loop

You do three things: start a workflow, wait for PPS to tell you a result is ready, then read it.

```mermaid
sequenceDiagram
    autonumber
    participant You
    participant PPS
    participant Endpoint as Your endpoint
    You->>PPS: POST /v1/sessions/{id}/workflows
    PPS-->>You: 202 workflowId
    Note over PPS: the product runs
    PPS->>Endpoint: workflow.updated, data.status "ready"
    You->>PPS: GET /v1/findings/workflows/{workflowId}/findings
    PPS-->>You: the findings
```

No event fires when you start a workflow. The delivery arrives later, when there is something to read.

## What you need from PPS

Most of these come from a person and can take days, so ask before you write any code.

- **A PPS access token.** See [Obtaining An Access Token](https://docs.pitchpointsolutions.com/developer_guides/authentication/access_token/).
- **Your org unit GUID**, a string like `OU41502`, which your PPS account manager supplies. You need it to register a webhook endpoint.
- **An authorized destination domain.** PPS must authorize the domain your endpoint lives on before it will send anything there; ask your PPS account manager.
- **The `service` and `model` values your account can start workflows for**, which your PPS account manager also supplies, because no endpoint lists them.
- **For outcome-based billing only:** your product set up to take outcome reports, and the permission to report granted to your integration system's credential. See [Reporting Outcomes](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/reporting_outcomes/).

## Where to go next

- [Getting Started](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/getting_started/) — authenticate, stage your data, start a workflow and read its result, step by step.
- [Failures and Reconfirms](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/failures_and_reconfirms/) — what to do when a run fails, how to run a workflow again, and how to find a lost one.
- [Reporting Outcomes](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/reporting_outcomes/) — tell PPS what became of each application, for products billed on outcomes.
- [Error Handling](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/error_handling/) — the two error shapes, how to branch on them, and limits worth knowing.
- [Retrying Safely](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/retrying_safely/) — retry a call that timed out without doing the work twice.
- [Session API Reference](https://docs.pitchpointsolutions.com/api/session/index/) and [Workflow API Reference](https://docs.pitchpointsolutions.com/api/workflow/index/) — every operation, field and response.