Get job works

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": "query GetJobWorks($workspaceId: ID!, $connectionId: ID!, $filters: JobWorkFilters) { me { workspaces(filters: { ids: [$workspaceId] }) { id connections(filters: { ids: [$connectionId] }) { id jobWorks(filters: $filters) { id createdAt updatedAt workspaceId workId connectionJobId work { id name externalId status tag } jobWorkArtifacts { id artifactId workArtifact { id externalId name type status } } } } } } }",
    "variables": {
      "workspaceId": "workspace_123456",
      "connectionId": "connection_789",
      "filters": {
        "ids": ["job_work_456"]
      }
    }
  }'

{
  "data": {
    "me": {
      "workspaces": [
        {
          "id": "workspace_123456",
          "connections": [
        {
          "id": "connection_789",
          "jobWorks": [
            {
              "id": "job_work_456",
              "createdAt": "2024-01-15T10:35:00Z",
              "updatedAt": "2024-01-15T10:40:00Z",
              "workspaceId": "workspace_123456",
              "workId": "work_789",
              "connectionJobId": "job_123456",
              "work": {
                "id": "work_789",
                "name": "John Smith - 2024 Tax Return",
                "externalId": "client-12345",
                "status": "pending",
                "tag": "individual"
              },
              "jobWorkArtifacts": [
                {
                  "id": "job_artifact_001",
                  "artifactId": "artifact_001",
                  "workArtifact": {
                    "id": "artifact_001",
                    "externalId": "file-w2-001",
                    "name": "W-2 Form 2024",
                    "type": "w2",
                    "status": "completed"
                  }
                }
              ]
            }
          ]
        }
      ]
        }
      ]
    }
  }
}

Retrieve job works associated with a provider connection. Job works represent individual client/tax preparation entries that were created as part of an import job. You can filter by specific job work IDs, connection job IDs, or work IDs.

query GetJobWorks($workspaceId: ID!, $connectionId: ID!, $filters: JobWorkFilters, $sortBy: SortBy, $offset: Int, $limit: Int) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: { ids: [$connectionId] }) {
        id
        jobWorks(filters: $filters, sortBy: $sortBy, offset: $offset, limit: $limit) {
          id
          createdAt
          updatedAt
          workspaceId
          workId
          connectionJobId
          work {
            id
            name
            externalId
            status
            tag
          }
          jobWorkArtifacts {
            id
            artifactId
            workArtifact {
              id
              externalId
              name
              type
              status
            }
          }
        }
      }
    }
  }
}

Arguments

connectionId

ID!

required

The ID of the provider connection to query job works from. This is the connection ID returned from startProviderConnection.

filters

JobWorkFilters

Optional filters to narrow down the job works returned.

Show JobWorkFilters

filters.ids

[ID!]

Filter by specific job work IDs. Use this to retrieve one or more specific job works by their unique identifiers.

filters.connectionJobIds

[ID!]

Filter by connection job IDs. Returns all job works that belong to the specified connection jobs.

filters.workIds

[ID!]

Filter by work IDs. Returns all job works associated with the specified works.

sortBy

SortBy

Optional sorting configuration.

Show SortBy

sortBy.field

String!

Field to sort by (e.g., “createdAt”, “updatedAt”).

sortBy.order

SortByOrder!

Sort direction: ASC for ascending or DESC for descending.

offset

Int

Number of records to skip for pagination. Defaults to 0.

limit

Int

Maximum number of records to return. Use with offset for pagination.

Returns

ID!

The unique identifier of the job work.

createdAt

Date!

Timestamp when the job work was created.

updatedAt

Date!

Timestamp when the job work was last updated.

workspaceId

ID!

The workspace ID this job work belongs to.

workId

ID!

The work ID this job work references.

connectionJobId

ID!

The connection job ID this job work belongs to.

work

Work!

The associated work (client/tax preparation) details.

Show Work fields

work.id

ID!

The unique identifier of the work.

work.name

String!

The name of the work (typically the client name).

work.externalId

String!

Your platform’s unique identifier for this work.

work.status

String!

The current status of the work:

pending - Work created but not yet imported
imported - Work successfully imported into Filed
error - An error occurred during import
deleted - Work has been removed

work.tag

String

Optional tag associated with the work.

jobWorkArtifacts

[JobArtifact!]!

List of artifacts attached to this job work. See get-job-work-artifacts for detailed artifact status information.

Example: Get Job Work by ID

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": "query GetJobWorks($workspaceId: ID!, $connectionId: ID!, $filters: JobWorkFilters) { me { workspaces(filters: { ids: [$workspaceId] }) { id connections(filters: { ids: [$connectionId] }) { id jobWorks(filters: $filters) { id createdAt updatedAt workspaceId workId connectionJobId work { id name externalId status tag } jobWorkArtifacts { id artifactId workArtifact { id externalId name type status } } } } } } }",
    "variables": {
      "workspaceId": "workspace_123456",
      "connectionId": "connection_789",
      "filters": {
        "ids": ["job_work_456"]
      }
    }
  }'

{
  "data": {
    "me": {
      "workspaces": [
        {
          "id": "workspace_123456",
          "connections": [
        {
          "id": "connection_789",
          "jobWorks": [
            {
              "id": "job_work_456",
              "createdAt": "2024-01-15T10:35:00Z",
              "updatedAt": "2024-01-15T10:40:00Z",
              "workspaceId": "workspace_123456",
              "workId": "work_789",
              "connectionJobId": "job_123456",
              "work": {
                "id": "work_789",
                "name": "John Smith - 2024 Tax Return",
                "externalId": "client-12345",
                "status": "pending",
                "tag": "individual"
              },
              "jobWorkArtifacts": [
                {
                  "id": "job_artifact_001",
                  "artifactId": "artifact_001",
                  "workArtifact": {
                    "id": "artifact_001",
                    "externalId": "file-w2-001",
                    "name": "W-2 Form 2024",
                    "type": "w2",
                    "status": "completed"
                  }
                }
              ]
            }
          ]
        }
      ]
        }
      ]
    }
  }
}

Example: Get All Job Works for a Connection Job

Query all job works that belong to a specific connection job:

query GetJobWorksByConnectionJob($workspaceId: ID!, $connectionId: ID!, $connectionJobId: ID!) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: { ids: [$connectionId] }) {
        id
        jobWorks(filters: { connectionJobIds: [$connectionJobId] }) {
          id
          work {
            id
            name
            externalId
            status
          }
        }
      }
    }
  }
}

The jobWorks field on a connection returns all job works across all connection jobs for that connection. Use the connectionJobIds filter to narrow down to a specific import batch.

Troubleshooting

Problem: No job works returned despite creating them Solutions:

Verify you’re querying the correct connection ID
Check that the job work IDs in your filter are correct
Ensure the job works were successfully created (check for errors in the createJobWorks response)
Confirm you have access to the workspace containing the connection

Problem: Missing artifact information Solutions:

Artifacts may not have been created yet - verify with createJobWorkArtifacts
Include the jobWorkArtifacts field in your query to fetch artifact details
Check artifact status to see if files are still being processed

Create job work artifacts

Get job work artifact status

APIs

Guides

API Reference

Arguments

Returns

Example: Get Job Work by ID

Example: Get All Job Works for a Connection Job

Troubleshooting

​Arguments

​Returns

​Example: Get Job Work by ID

​Example: Get All Job Works for a Connection Job

​Troubleshooting

Arguments

Returns

Example: Get Job Work by ID

Example: Get All Job Works for a Connection Job

Troubleshooting