> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create job works

> Attach clients to an import job

Attach one or more clients (works) to a connection job. Each work represents a tax preparation for a specific client. You can create multiple works in a single request.

```graphql theme={null}
mutation CreateJobWorks($connectionJobId: ID!, $inputs: [CreateJobWorksInput!]!) {
  createJobWorks(connectionJobId: $connectionJobId, inputs: $inputs) {
    id
    createdAt
    updatedAt
    workspaceId
    workId
    connectionJobId
  }
}
```

## Arguments

<ParamField path="connectionJobId" type="ID!" required>
  The ID of the connection job returned from [createConnectionJob](/legacy/apis/endpoint/create-connection-job). This groups the works together for batch processing.
</ParamField>

<ParamField path="inputs" type="[CreateJobWorksInput!]!" required>
  Array of work inputs. Each input represents one client/tax preparation to attach to the job.

  <Expandable title="CreateJobWorksInput">
    <ParamField path="inputs[].name" type="String!" required>
      Client name or tax preparation identifier. This is typically the client's name or a descriptive identifier for the tax prep (e.g., "John Smith - 2024 Tax Return", "client-12345").
    </ParamField>

    <ParamField path="inputs[].externalId" type="String!" required>
      Your platform's unique identifier for this client or tax preparation. This external ID is used to correlate the work with your system and should be unique within your platform.
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="id" type="ID!">
  Job work identifier. Save this for creating job work artifacts (attaching files).
</ResponseField>

<ResponseField name="createdAt" type="Date!">
  Timestamp when the job work was created.
</ResponseField>

<ResponseField name="updatedAt" type="Date!">
  Timestamp when the job work was last updated.
</ResponseField>

<ResponseField name="workspaceId" type="ID!">
  The workspace ID this job work belongs to.
</ResponseField>

<ResponseField name="workId" type="ID!">
  The work ID this job work references.
</ResponseField>

<ResponseField name="connectionJobId" type="ID!">
  The connection job ID this job work belongs to.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <accessToken>" \
    -H "source-platform: my-sample-platform" \
    -d '{
      "query": "mutation CreateJobWorks($connectionJobId: ID!, $inputs: [CreateJobWorksInput!]!) { createJobWorks(connectionJobId: $connectionJobId, inputs: $inputs) { id createdAt updatedAt workspaceId workId connectionJobId } }",
      "variables": {
        "connectionJobId": "job_123456",
        "inputs": [
          {
            "name": "John Smith - 2024 Tax Return",
            "externalId": "client-12345"
          },
          {
            "name": "Jane Doe - 2024 Tax Return",
            "externalId": "client-67890"
          }
        ]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "createJobWorks": [
        {
          "id": "job_work_789",
          "createdAt": "2024-01-15T10:35:00Z",
          "updatedAt": "2024-01-15T10:35:00Z",
          "workspaceId": "workspace_123456",
          "workId": "work_789",
          "connectionJobId": "job_123456"
        },
        {
          "id": "job_work_790",
          "createdAt": "2024-01-15T10:35:00Z",
          "updatedAt": "2024-01-15T10:35:00Z",
          "workspaceId": "workspace_123456",
          "workId": "work_790",
          "connectionJobId": "job_123456"
        }
      ]
    }
  }
  ```
</ResponseExample>

<Note>
  After creating job works, use [createJobWorkArtifacts](/legacy/apis/endpoint/create-job-work-artifacts) to attach files to each job work. The `externalId` should match your platform's client identifier to enable correlation between Filed and your system.
</Note>

## Troubleshooting

**Problem**: `createJobWorks` fails with invalid connection job ID

**Solutions**:

* Verify the `connectionJobId` exists and belongs to your connection
* Ensure you're using the `id` from the `createConnectionJob` response
* Check that the connection job status allows adding works

**Problem**: Duplicate external IDs

**Solutions**:

* Ensure each `externalId` is unique within your platform
* If you need to create multiple works for the same client, use different external IDs (e.g., add a suffix or timestamp)
* Verify you're not accidentally reusing external IDs from previous imports