# Start a Workflow in a Session Source: https://docs.pitchpointsolutions.com/api/session/start_session_workflow/ **Beta** Starts a workflow against the data staged in this session, and returns a workflow handle for following it. This is the reason the session API exists. The body names a product, plus an optional `correlationId` for this run. **Starting a workflow records no snapshot** — it reads what the session already holds. The workflow runs against whatever snapshot is current at the moment you start it; staging again afterwards does not reach a workflow already running. A later [reconfirm](https://docs.pitchpointsolutions.com/api/workflow/reconfirm_workflow/) of that workflow does see it. > **Before Starting:** Get the URL to submit against from your Pitchpoint Account Representative, along with the `service` and `model` values your account is entitled to use. There is no endpoint that lists them. > **Warning:** **This call starts a real workflow and is billed.** Stage once, start as many workflows as you need — but each is independently billed, not a retry of the last one. Two workflows against one session give you two independent workflows, neither a reconfirm of the other. Nothing earlier in the session flow costs anything; this is the call that does. ### Sample ```bash url="https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/workflows" curl -X POST "${url}" \ -H "Authorization: Bearer your_access_token_here" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "product": { "service": "ADV", "model": "FirstOrder" }, "correlationId": "alpha_numeric_string_to_help_identify_this_workflow" }' ``` #### Header Properties | Property | Value | Required? | |---------------------------|------------------------|-----------| | Authorization | Bearer *your token* | true | | Content-Type | application/json | true | | Accept | application/json | false | | X-PPS-UserAlias | *your value* | false | | X-PPS-UserAgent | *your value* | false | | X-PPS-CorrelationID | *your value* | false | | Idempotency-Key | *a V4 UUID* | false | Send `Content-Type: application/json` on **every** POST, including one with no body at all. In deployed environments a request that arrives without it is refused by edge protection in front of the application, with a `403` carrying an HTML body rather than any response documented here — and because the service never sees the request, nothing can explain it to you. A local or unprotected deployment may accept the same request, so do not take a working call there as evidence the header is optional. `Accept` is not enforced — a request without it is answered normally with JSON — but send it anyway, so that a future change to content negotiation cannot alter what you receive. `X-PPS-CorrelationID` is a **support-tracing header and is not the same thing** as the `correlationId` field in a request body. Only the body field is recorded against an order and searched by [Find Workflows](https://docs.pitchpointsolutions.com/api/workflow/list_workflows/); setting the header globally in your HTTP client does not make your orders findable. `Idempotency-Key` makes a retry of this call safe: send the same request again with the same key and you get the first response back, marked `X-Pps-Idempotent-Replay: true`, instead of the work being done twice. Use a new V4 UUID for each request. A key can be 1 to 255 characters; never put sensitive data in it. See [Retrying Safely](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/retrying_safely/). See the [Common Headers guide](https://docs.pitchpointsolutions.com/developer_guides/headers/index/) for details on the optional `X-PPS-*` headers above. #### Path Parameters | Property | Description | Type | |-----------|--------------------------------------------------------------------|--------| | sessionId | (mandatory) The session holding the data to run against. | string | #### Request Data Properties | Property | Description | Type | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|--------| | product | (mandatory) The product to run, as a structured selector. See section below. | object | | correlationId | (optional) Your own reference for **this run**, at most 255 characters. Not required to be unique. This is the value [Find Workflows](https://docs.pitchpointsolutions.com/api/workflow/list_workflows/) searches. Leading and trailing whitespace is trimmed, and a blank value is treated as absent. Longer than 255 characters is a 400 `VALIDATION_ERROR`, and nothing is started. A value that resembles SQL or markup is refused at the edge with no JSON body, so encode such a value (Base64, for instance) rather than sending it raw. Not the same as a term's `correlationId`; see [Correlation ids on terms](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/#correlation-ids-on-terms). | string | Fields this call doesn't define are ignored. ##### product | Property | Description | Type | |----------|----------------------------------------------------------------------------------------------|--------| | service | (mandatory) The product family, for example `ADV`. | string | | model | (mandatory) The model within that family, for example `FirstOrder`. Matched ignoring case; a response gives it back in the spelling the product catalog uses. | string | Both parts are required, and both are free text rather than a closed list. A pair that does not resolve to a product you may use is rejected — see the 400 below. > **Warning:** **Terms do not belong here.** The data comes from the session. A `terms` field on this body is ignored, not applied. To change the data, [stage it again](https://docs.pitchpointsolutions.com/api/session/stage_session_sami/) first and then start the workflow. **The session's `correlationId` is not inherited.** This workflow carries its own or none at all, and only the one supplied here is searchable. ### Responses > **Warning:** **Not every response carries the same body. Branch on the `Content-Type` first, and then on what the body contains.** `application/json` is the `messages` envelope described on this page: read `messages[].code`. `application/problem+json` is a problem document, with `type`, `title`, `status`, `detail` and `instance` and no `messages` key: read `type`, and compare it as the whole URI (for example `https://pointservices.com/problems/concurrent-modification`). Some rejections carry no JSON at all. A client that calls its JSON parser on every non-2xx body, or that reads `messages[0].code` without first checking that `messages` is present, will fail on the responses it is most likely to meet. See [Error handling](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/error_handling/) for the whole rule. **202** Accepted for processing. The workflow now exists and is readable immediately — you may [read it](https://docs.pitchpointsolutions.com/api/workflow/get_workflow/) the instant you receive this. A retry under the same `Idempotency-Key` returns this same 202, byte for byte, with the header `X-Pps-Idempotent-Replay: true`, naming the same `workflowId`. No second workflow is started or billed. See [Retrying Safely](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/retrying_safely/). | Property | Description | Type | |----------|---------------------------------------------------------------------------------------------------------------------------------------|--------| | workflow | (present) The workflow this call started. See section below. | object | | messages | (present) Always an array, never null. Carries one message whose `code` is `ACCEPTED`. | array | ##### workflow | Property | Description | Type | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| | workflowId | (present) The handle for every later read and reconfirm, `wfpop_`-prefixed. Stable for the life of the workflow, including across reconfirms. | string | | runId | (present) Identifies this one execution, `wfrunpop_`-prefixed. **No endpoint accepts a `runId`** — it exists to match this response to a webhook event's `data.runId`. | string | | status | (present) `processing` on an acknowledgment. Lowercase, one of `processing`, `complete`, `failed`, `cancelled`. | string | | sessionId | (present) The session this was started against — your way back to the data. | string | | correlationId | (optional) Your value for this run, echoed back. Absent when none was sent. | string | | product | (present) The resolved product selector. | object | | productType | (present) The product family, matching `product.service`. | string | | productName | (present) The model, matching `product.model`. | string | | reconfirmAvailable | (optional) `false` on an acknowledgment, which says nothing about whether a reconfirm will ever be available. Whether it turns `true` later depends on the product, not merely on time passing — see [Reconfirm a Workflow](https://docs.pitchpointsolutions.com/api/workflow/reconfirm_workflow/). | boolean | **No timestamps are set on an acknowledgment.** `ordered`, `fulfilled`, `completed` and `serviceable` are all absent until the workflow has been recorded; the only time in this response is the message's own `timestamp`. Every optional field is omitted rather than null when the stage that would set it has not happened. Example: ```json { "workflow": { "workflowId": "wfpop_0000000000002080001", "runId": "wfrunpop_0000000000002080001", "sessionId": "0000000000013500001", "correlationId": "alpha_numeric_string_to_help_identify_this_workflow", "product": { "service": "ADV", "model": "FirstOrder" }, "productType": "ADV", "productName": "FirstOrder", "status": "processing", "reconfirmAvailable": false }, "messages": [ { "code": "ACCEPTED", "text": "workflow accepted for processing", "timestamp": "2026-08-07T15:01:42Z" } ] } ``` **400** The workflow was refused and **nothing was billed**. Causes: an absent or blank body; `product` absent, malformed, or carrying only one of `service` and `model`; a `service` and `model` pair that does not resolve to a product you may use; a `correlationId` longer than 255 characters. A literal `null` body, malformed JSON, and a `Content-Type` naming an unusable character set are refused before evaluation, as problem documents. An `Idempotency-Key` that is blank, longer than 255 characters, or already used with a different body is also refused with `VALIDATION_ERROR`. A 400 is never stored. After fixing a problem in the body, send it again with the same key. After a key-reuse 400, see [Retrying Safely](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/retrying_safely/#when-to-make-a-new-key). The empty-session check runs **before** product resolution, so an unresolvable product against an empty session returns the 409 below, not this 400. Once the session holds data, the same request returns this 400. The shape checks come first of all: a missing or half-supplied `product`, or a `correlationId` over 255 characters, is this 400 even on an empty session. An unresolvable product pair will not become resolvable on its own. **Correct the product rather than retrying** — the same request returns the same 400. A 400 arrives in **two different body shapes**, decided by how far the request got before it was refused. Branch on the `Content-Type`: `application/json` is the `messages` envelope, and `application/problem+json` is a problem document. **A value this service evaluated and rejected** carries the `messages` envelope, with `Content-Type: application/json` and the code `VALIDATION_ERROR`. | Property | Description | Type | |----------------------|----------------------------------------------------------------------------------------------------------------|--------| | messages | (present) Always an array, never null. Carries one message whose `code` is `VALIDATION_ERROR`. | array | | messages[].code | (present) Always `VALIDATION_ERROR` on this shape. | string | | messages[].text | (present) Human-readable description of what was wrong. Never machine-parsed — the wording is not contractual. | string | | messages[].timestamp | (present) RFC 3339 UTC with a trailing `Z`. Fractional seconds appear only when they are not zero, so parse this value rather than slicing it. | string | Example: ```json { "messages": [ { "code": "VALIDATION_ERROR", "text": "the requested product does not resolve", "timestamp": "2026-08-07T15:01:42Z" } ] } ``` **A request refused before any value was evaluated** carries a problem document instead, with `Content-Type: application/problem+json` and **no `messages` key and no `VALIDATION_ERROR` code**. Its `type` tells you which case it is: | Cause | `type` | |-------|--------| | A body that could not be read as a workflow start at all: malformed JSON, a literal `null` body, a JSON array or bare value where an object was expected, or a field that can't be read as its type | `about:blank` | | A `Content-Type` header naming a character set this service cannot use. It is refused before the body is read, so it says nothing about what you put in it. | `https://pointservices.com/problems/invalid-request` | Example: ```json { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Malformed JSON", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } ``` > **Warning:** A client that reads `messages[0].code` on every 400 without checking that `messages` exists will throw on the problem-document shape. Branch on the `Content-Type`, or on the presence of `messages`, not on the status. No workflow is started, no handle is issued, and the session's data is left exactly as it was. **401** No credential the platform could accept reached the service. The body is a **JSON problem document**, not the `messages` envelope, and the response carries a `WWW-Authenticate: Bearer realm="Helix"` challenge. Read the machine-readable part from `type`; `title` and `detail` are human copy and are not contractual. | Property | Description | Type | |----------|--------------------------------------------------------------------------------------------------------|--------| | type | (present) An absolute URI identifying the problem. `about:blank` when no credential was sent at all. | string | | title | (present) Short human-readable summary. | string | | status | (present) Repeats the HTTP status code. | number | | detail | (present) Human-readable explanation. Never machine-parsed. | string | | instance | (present) An identifier for this one request. Quote it when contacting support. | string | Examples: ```json { "type": "about:blank", "title": "Unauthorized", "status": 401, "detail": "Authentication is required. Present a bearer access token in the Authorization header.", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } { "type": "https://pointservices.com/problems/invalid-token", "title": "The access token was not accepted", "status": 401, "detail": "The access token was rejected.", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } ``` The second form carries `WWW-Authenticate: Bearer realm="Helix", error="invalid_token"`, and is what a token the service will not accept returns. The `invalid-token` type deliberately does not say why the token was refused: the platform cannot tell an expired token from a revoked, badly signed or malformed one. Treat every `invalid-token` the same way. > **Warning:** **Refresh your token on a 401, and only on a 401.** An expiring token moves a call from 200 to 401, never to 403. Obtain a fresh access token and retry the request once. If it fails again, stop and surface the error rather than looping — repeated attempts with a credential the service has already refused will meet the rate throttle described below. **403** Either you are not permitted to start a workflow in this session, or your account is not entitled to the product you requested. An entitlement problem is the more common of the two: check the `service` and `model` against what your Account Representative provisioned. No workflow is started and nothing is billed. A 403 is an **authorization decision**: your identity was established and the answer is still no. It is never a statement about your token, so refreshing the token will not turn it into a 200. A refused request leaves nothing behind, so there is nothing to clean up. The body is a problem document (`application/problem+json`), not the `messages` envelope, so there is no `code` to branch on. Its `type` is one of two values: | `type` | Meaning | |--------|---------| | `about:blank` | The request was denied before the operation itself ran. | | `https://pointservices.com/problems/not-authorized` | A policy decision about the specific resource or product you named. | Example: ```json { "type": "https://pointservices.com/problems/not-authorized", "title": "Not authorized", "status": 403, "detail": "The authenticated identity is not permitted to perform this action.", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } ``` > **Warning:** **A 403 can also come from the edge, before this service is reached,** when a request omits `Content-Type` or carries a value resembling SQL injection or cross-site scripting. That refusal carries an HTML body, not a problem document, and this service never sees it. Check the `Content-Type` of the response before you parse it. A value that legitimately contains such text should be encoded — Base64, for instance — rather than sent raw. **404** No session exists with this identifier, or the path you called is not served. When this API answers, the body is a problem document (`application/problem+json`) in both cases, and its `type` tells them apart. **`https://pointservices.com/problems/not-found`** means the identifier you sent did not resolve. | Property | Description | Type | |----------|--------------------------------------------------------------------------------------------|--------| | type | (present) `https://pointservices.com/problems/not-found` here. Compare it as the whole URI. | string | | title | (present) Short human-readable summary. | string | | status | (present) Repeats the HTTP status code. | number | | detail | (present) Human-readable explanation naming what was not found. Never machine-parsed. | string | | instance | (present) An identifier for this one request. Quote it when contacting support. | string | Example: ```json { "type": "https://pointservices.com/problems/not-found", "title": "No such resource", "status": 404, "detail": "Session[0000000000013500001] not found", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } ``` Treat this as a single outcome: nothing in the body narrows down why the identifier did not resolve. Check the identifier you sent, and the tenancy of the credential you sent it with. An identifier this API has already issued to you is readable the moment you receive it, so a 404 on one is final rather than a race. Retrying will not make it appear. **`about:blank`** means the path itself is not served here, so the request never reached this operation: a wrong host, or an environment where this API is not deployed. A URL missing the `/riskinsight-services-ws/resources/v1` path prefix does not reach this API at all. The 404 then comes from infrastructure in front of it, and carries no body this API defines, so don't try to parse it. If a 404 has no problem document, check the path prefix before anything else. **409** `IDEMPOTENCY_IN_PROGRESS` — an earlier request under the same `Idempotency-Key` is still running. **This is the one 409 to retry:** wait the number of seconds in the `Retry-After` header, then send the same request with the same key. If it persists for more than a few minutes, stop and follow [When the 409 doesn’t go away](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/retrying_safely/#when-the-409-doesnt-go-away). `SESSION_EMPTY` — nothing has been staged into this session, so there is nothing to run against. [Stage data](https://docs.pitchpointsolutions.com/api/session/stage_session_sami/) first, then try again. You resolve it yourself, by staging, and it is deliberately not a `VALIDATION_ERROR`: the session was empty, and the corrective action is different. It says nothing about the product: once data is staged, an unresolvable product returns the 400. Nothing is billed, because the request is refused before anything is dispatched. A concurrent change to this session, which lost the race. This arrives as a `concurrent-modification` problem document, described below. Treat a `WORKFLOW_WRITE_CONFLICT` code in the envelope the same way. Either way the service does not retry it, so you decide whether to resubmit. **Branch on the `Content-Type` first, and only then on `messages[].code`.** A 409 here arrives in two body shapes, and the corrective action differs by cause. Never branch on the status alone, and never read `messages[0].code` without checking that `messages` is present. **`application/json`** carries the `messages` envelope: | Property | Description | Type | |----------------------|-----------------------------------------------------------------------------------------------------------|--------| | messages | (present) Always an array, never null. | array | | messages[].code | (present) One of the codes described above for this status. | string | | messages[].text | (present) Human copy. Never machine-parsed. | string | | messages[].timestamp | (present) RFC 3339 UTC with a trailing `Z`, fractional seconds only when they are not zero. | string | **`application/problem+json`** carries a problem document with `type` `https://pointservices.com/problems/concurrent-modification` and no `messages` key. Another request changed the same resource while yours was in flight, and **nothing from yours was applied**. It carries no `Retry-After`, deliberately: read the resource again, decide whether your change still applies to what you now see, and resubmit only if it does. Don't resend the same request on a timer. Example: ```json { "type": "https://pointservices.com/problems/concurrent-modification", "title": "Concurrent modification", "status": 409, "detail": "The resource was modified by another request while this one was being processed. This request was not applied; re-read the resource before resubmitting.", "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000" } ``` In either shape the conflict is final for that attempt: the service does not retry it for you. The one exception is `IDEMPOTENCY_IN_PROGRESS`, which always arrives in the `messages` envelope and which you retry after the `Retry-After` delay. **429** Refused by a rate throttle at the edge, before this service is reached. The throttle counts requests per source address across every endpoint on both the session and workflow surfaces. Because the edge sends this response before the request reaches the service, it is not described in the OpenAPI specifications or the API Explorer. The refusal carries no body, no `messages` array and no `Retry-After` header, and this service never sees it, so it will not appear in any support trace. Back off and resume. When following a workflow to completion, an interval that stays clear of the throttle is two seconds for the first two checks, then five, then ten seconds thereafter, with an overall deadline after which you stop and investigate. **500** An unhandled failure inside the service. The body is a problem document (`application/problem+json`) with `type` `about:blank`, not the `messages` envelope, so branch on the status alone. When you report the error to PPS, quote the document's `instance`: it carries the same id as the `x-pps-request-id` response header, and it is what lets PPS find this exact request. > **Warning:** **Retrying this call is not safe.** A 500 means the outcome is **unknown**, not that nothing happened: a failure raised after the work was committed leaves that work in place. **A workflow may have been started and billed.** Do not simply retry. A 500 on this call is stored: a retry under the same `Idempotency-Key` returns the same 500. Search [Find Workflows](https://docs.pitchpointsolutions.com/api/workflow/list_workflows/) for the `correlationId` you sent, and start another, under a **new** key, only if nothing comes back — which is the reason to send a distinctive one every time. Without an `Idempotency-Key`, retrying blind is how one workflow becomes two, and nothing on this surface removes a duplicate for you.