Skip to content
API Documentation

Job

Resource representing a job belonging to a user in your workspace.

The Job resource is the core entity you'll work with in Worklayer. A job is a link between the user and a Taxfyle tax professional or Pro. It serves as a unit of work in the Worklayer system, usually representing some amount of work required to be completed by a Pro and containing the information necessary to complete that work; such as a filer's tax situation information, tax package selected, documents, and statuses to track completion progress.

With the API, you can list jobs in your workspace and request specific jobs via their ID or short ID. See the List Jobs documentation for getting your user's jobs or jobs in a certain status.

You can also create jobs for your users, add documents to them, and submit them to the pool of Taxfyle Pros. For details on the job creation flows, check the Job Creation Flow Reference Page

Endpoints

MethodUrl
GET/v1.0/jobs
GET/v1.0/jobs/{job_id}
GET/v1.0/jobs/getByShortId:{short_id}
POST/v1.0/jobs/{job_id}/job_link
POST/v1.0/jobs
GET/v1.0/jobs/{job_id}/questionnaire
PUT/v1.0/jobs/{job_id}/questionnaire/answers
POST/v1.0/jobs/{job_id}/submit
GET/v1.0/jobs/{job_id}/documents
GET/v1.0/jobs/{job_id}/checklist
POST/v1.0/jobs/{job_id}/requested-provider
POST/v1.0/jobs/{job_id}/requested-provider/request-previous

Job Properties

id
The Job's ID.
short_id
The Job's short Id. An alternative ID for the job.
name

The Job's name. This can be set by the Client or Pro depending on permissions and can be a string or null.

description

The Job's description is typically shown around the worklayer UI. This value can vary depending on how your workspace was configured. Usually, it describes the type of work to be done.

status

The current status this job is in. A job goes through the following statuses throughout its lifetime:

  • UNDER_CONSTRUCTION - The job is in draft and still accessible by the owner for modification
  • INFO_GATHERING - The job has been submitted but is not yet available in the pool; the client is requested to provide their supporting documentation.
  • UNCLAIMED - The job has been submitted to the pool and is waiting to be picked up by a Pro
  • CLAIMED - Ths job has been picked up by a Pro and is being worked on. This can also be considered as In-Progress
  • IDLE - The job goes into Idle status after inactivity from all parties on the job.
  • ON_HOLD - The job was marked on hold by either the Pro or an Admin
  • COMPLETED - The job has been marked completed. The Pro can't communicate with the client once the job is completed.
  • CANCELLED - The job has been cancelled. The Pro can't communicate with the client once the job is closed.
create_time

When the job was created. A timestamp in format 2021-04-28T13:45:25.781Z.

update_time

When the job was updated. A timestamp in format 2021-04-28T13:45:25.781Z.

transmit_time

The date the job was submitted to the pool for matching. This is null while the job is UNDER_CONSTRUCTION. A timestamp in format 2021-04-28T13:45:25.781Z otherwise.

deadline_time

The date marked as the deadline for this job to be completed by. Either null or a timestamp in format 2021-04-28T13:45:25.781Z.

total_amount

A number representing the price for services performed by Taxfyle. This amount varies with the services included in the job.

requested_provider
•
object

If set, an object containing the requested Pro's user ID. This is set when the Client requests a specific Pro to work on their job. See the Job Requested Provider Properties section below for details.

members
•
array

An array of the Job Members of this job. When the job is UNDER_CONSTRUCTION or UNCLAIMED this will only have one element: the client. Once a Pro picks up the job, the Pro will be another entry in this array. See the Job Member Properties section below for details.

current_progress_step
•
object

An object containing the current progress of the Job. See the Current Progress Step section below for details.

scope
•
object

An object containing the current scope of services performed on a job. See the Scope section below for details.



Requested Provider Properties

user_id
The user ID of the Provider that has been requested.


Job Member Properties

role

Members of a job can have two kinds of roles:

  • CHAMPION - The primary collaborator of their type
  • SUPPORTING - A supporting collaborator of their type

Typically jobs have two members, the Client, and the Pro. However, there could be instances where a job has more than two collaborators. They'll be marked with the SUPPORTING type.

type

The type of collaborator the user is on the job. One of: - CLIENT - The owner of the job - PROVIDER - The Taxfyle Pro providing the services

user_id
The user ID of the Job Member.
given_name
The user's given name. Also known as the first name.
family_name
The user's family name. Also known as the last name.
display_name

A string that can be used for display purposes. Usually a combination of the given name and family name.



Current Progress Step Properties

step

The step where the current step could be.

  • JOB_STARTED - The job has been started by the Pro.
  • OPEN_ITEMS - The Pro has identified that there are missing items from the Client.
  • DRAFT_IN_REVIEW - The Pro has submitted a draft return for the Client to review.
  • DRAFT_REJECTED - The Client rejected the draft return.
  • DRAFT_APPROVED - The Client approved the draft return.
  • AUTHORIZATION_REQUESTED - The Pro has requested the Client's authorization to file the return.
  • AUTHORIZATION_SIGNED - The Client signed the authorization request.
  • RETURN_FILED - The tax return was filed.
date_updated

When the job progress was updated. A timestamp in format. 2021-04-28T13:45:25.781Z.



Scope Properties

services
•
array

An array of services being performed on the job.

consultation
•
object

An object containing the scheduled time of the consultation on the job, if any. A timestamp in format. 2021-04-28T13:45:25.781Z.

Copied
1{
2  "id": "499d692d-67aa-4127-a45c-b9e27f54afad",
3  "short_id": "TWQXJWMABW8",
4  "name": null,
5  "description": "Tony Stark | 2021 | 1040",
6  "status": "CLAIMED",
7  "create_time": "2021-04-28T13:45:25.781Z",
8  "update_time": "2021-04-28T13:52:27.379Z",
9  "transmit_time": "2021-04-28T13:45:39.413Z",
10  "deadline_time": null,
11  "total_amount": 199,
12  "requested_provider": {
13    "user_id": "2c6e3172-8711-47fd-9436-61ef31ae796b"
14  },
15  "members": [
16    {
17      "role": "CHAMPION",
18      "type": "CLIENT",
19      "user_id": "a4feef24-00da-4340-8b7c-a532e0607fdd",
20      "given_name": "Tony",
21      "family_name": "Stark",
22      "display_name": "Tony Stark"
23    },
24    {
25      "role": "CHAMPION",
26      "type": "PROVIDER",
27      "user_id": "2c6e3172-8711-47fd-9436-61ef31ae796b",
28      "given_name": "Natasha",
29      "family_name": "Romanov",
30      "display_name": "Natasha Romanov"
31    }
32  ],
33  "current_progress_step": {
34    "step": "JOB_STARTED",
35    "date_updated": "2023-08-29T22:09:45.654879Z"
36  },
37  "scope": {
38    "services": [
39      "Form 1040",
40      "Consultation 15 Minutes"
41    ],
42    "consultation": {
43      "scheduled_time": "2023-12-04T13:00:00Z"
44    }
45  }
46}

Next steps

Last updated on November 27, 2023
Privacy PolicyTerms & Conditions© 2024 Taxfyle