Untitled

Preparing Your Data

Before sending data to Patchworks via the API, you need to decide which endpoint variant best fits your integration. There are now two ways to format and send a payload to trigger a process flow:

1. Standard (legacy) endpoints — the payload must be JSON-stringified and wrapped inside a payload key.

2. Raw endpoints — the payload is sent as a plain JSON object with no wrapping required.

Both approaches are fully supported and remain backwards-compatible.

---

Option 1 — Standard Payload Format (Legacy)

The original start and manual endpoints require the data to be serialised as a JSON string and nested under a payload key:

Endpoint:

POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/start/{version_id?}
POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/manual/{version_id?}

Request body:

{
    "payload": "{\"ORDER\": \"#LMUK62388\", \"DATA\": [{\"CARRIER\": \"EVRI\", \"QUANTITY\": \"3\", \"SKU\": \"42108803101\", \"HOST_LINE_ID\": \"17070133346600\", \"TRACKING_NUMBER\": \"T042RA0001996850\"}]}"
}

Note that the value of payload is a JSON string (i.e. the inner JSON has been serialised with escaped quotes). This is the expected format for these endpoints.

---

Option 2 — Raw Payload Format (Recommended for new integrations)

New /raw endpoint variants accept a standard JSON object directly in the request body — no wrapping or stringification is needed.

Endpoints:

POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/start/raw/{version_id?}
POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/manual/raw/{version_id?}

Request body:

{
    "ORDER": "#LMUK62388",
    "DATA": [
        {
            "CARRIER": "EVRI",
            "QUANTITY": "3",
            "SKU": "42108803101",
            "HOST_LINE_ID": "17070133346600",
            "TRACKING_NUMBER": "T042RA0001996850"
        }
    ]
}

Your JSON is sent exactly as-is — no additional serialisation step is required.

{% hint style="info" %} The version_id path parameter is optional. If omitted, Patchworks will use the currently deployed version of the flow. If no version is deployed, the request will return a 422 error. {% endhint %}

---

Example cURL Requests

Start (standard)

curl -X POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/start/{version_id} \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payload": "{\"ORDER\":\"#LMUK62388\",\"DATA\":[{\"CARRIER\":\"EVRI\",\"QUANTITY\":\"3\",\"SKU\":\"42108803101\",\"HOST_LINE_ID\":\"17070133346600\",\"TRACKING_NUMBER\":\"T042RA0001996850\"}]}"
  }'

Start (raw)

curl -X POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/start/raw/{version_id} \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ORDER": "#LMUK62388",
    "DATA": [
      {
        "CARRIER": "EVRI",
        "QUANTITY": "3",
        "SKU": "42108803101",
        "HOST_LINE_ID": "17070133346600",
        "TRACKING_NUMBER": "T042RA0001996850"
      }
    ]
  }'

Manual (standard)

curl -X POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/manual/{version_id} \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payload": "{\"ORDER\":\"#LMUK62388\",\"DATA\":[{\"CARRIER\":\"EVRI\",\"QUANTITY\":\"3\",\"SKU\":\"42108803101\",\"HOST_LINE_ID\":\"17070133346600\",\"TRACKING_NUMBER\":\"T042RA0001996850\"}]}"
  }'

Manual (raw)

curl -X POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/manual/raw/{version_id} \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ORDER": "#LMUK62388",
    "DATA": [
      {
        "CARRIER": "EVRI",
        "QUANTITY": "3",
        "SKU": "42108803101",
        "HOST_LINE_ID": "17070133346600",
        "TRACKING_NUMBER": "T042RA0001996850"
      }
    ]
  }'

---

Sending an Empty Payload

Both endpoint variants accept requests with no body. This triggers the flow with an empty payload:

curl -X POST https://start.wearepatchworks.com/api/v1/flows/{flow_id}/start/raw/{version_id} \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

---

Response

A successful request returns a 200 response containing either a scheduled_flow_id or a flow_run_id, depending on how the flow is configured:

{
    "scheduled_flow_id": 12345
}

or

{
    "flow_run_id": 67890
}

---

Error Responses

Status	Cause
401	Missing or invalid authentication credentials
403	Authenticated user does not have the "trigger flows" permission
422	Invalid flow_id, or version_id omitted and no deployed version exists

---

Which Endpoint Should I Use?

Scenario	Recommendation
Existing integration using the payload wrapper	Continue using the standard endpoint — no changes needed
New integration	Use the /raw endpoint — simpler payload construction, no JSON-string serialisation required
Sending data from a webhook, script, or third-party platform	Use the /raw endpoint for easier setup