Create Run

POST /api/v1/payroll-migrations/{migration_id}/runs/

Create a new run within a payroll migration. A run represents a payroll document from either the source (old) or target (new) provider.

Authentication

Requires an API key with migrations:write scope. Pass via the X-API-Key header.

Path Parameters

Parameter	Type	Description
`migration_id`	string (UUID)	The unique identifier of the parent migration.

Request

Content type: application/json

Body Parameters

Field	Type	Required	Description
`run_type`	string	Yes	Either `"source"` or `"target"`.
`document_id`	string (UUID)	Yes	The ID of an uploaded document to associate with this run.

Run types: A "source" run represents the payroll from the old provider (before migration). A "target" run represents the payroll from the new provider (after migration). Parsify compares source and target runs to validate that the migration was successful.

Response

Status: 201 Created

{
  "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
  "migration": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "run_type": "source",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-03-16T12:00:00Z",
  "updated_at": "2026-03-16T12:00:00Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique identifier for the run.
`migration`	string (UUID)	ID of the parent migration.
`run_type`	string	Either `"source"` or `"target"`.
`document_id`	string (UUID)	ID of the associated document.
`status`	string	Current status of the run.
`created_at`	string (ISO 8601)	Timestamp when the run was created.
`updated_at`	string (ISO 8601)	Timestamp when the run was last updated.

Errors

Status	Description
`400`	Missing or invalid request body fields, or invalid `run_type`.
`401`	Missing or invalid API key.
`403`	API key does not have `migrations:write` scope.
`404`	Migration or document not found.

Code Examples

curl -X POST https://api.parsifyhq.com/api/v1/payroll-migrations/b2c3d4e5-f6a7-8901-bcde-f12345678901/runs/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_type": "source",
    "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

import requests
 
migration_id = "b2c3d4e5-f6a7-8901-bcde-f12345678901"
 
resp = requests.post(
    f"https://api.parsifyhq.com/api/v1/payroll-migrations/{migration_id}/runs/",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "run_type": "source",
        "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
 
print(resp.json())

const migrationId = "b2c3d4e5-f6a7-8901-bcde-f12345678901";
 
const resp = await fetch(
  `https://api.parsifyhq.com/api/v1/payroll-migrations/${migrationId}/runs/`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      run_type: "source",
      document_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    }),
  }
);
 
const data = await resp.json();

Update Migration List Runs