A Job Request represent some work to be done (e.g. “I need 10 people tomorrow to stack boxes for 8 hours, starting at 10am”), so the first step in hiring Wonoloers will be to post to the Job Request service.

Job Request States, State Transitions

One of the most important aspects of a Job Request is its “state” which determines how workers may interact with it and indicate where in its lifecycle the job request is at.

The following are valid job states:


posted	Job Requests marked as "posted" are available to any eligible Worker and will show on the map in the Wonolo app. When a Job Request is posted, Workers are ranked and notified. Create a Job Request with a state of posted if you want ranking and notifying to begin immediately
unassigned	Job Requests marked as "unassigned" are invisible to Workers unless they are preferred (preferred workers are designated through the `preferred_candidate_ids` property)
unfilled	Job Requests marked as "unfilled" have no slots filled at the start time of the Job Request
filled	Job Requests marked as "filled" have all slots are filled but the start time is still in the future
in_progress	When a Job Request is marked as "in_progress" this indicates at least one Job is in progress
completed	When a Job Request is marked as "completed" this indicates all of the Jobs for the given Job Request are completed
approved	When a Job Request is marked as "approved" this means all of the Jobs for the given Job Request are approved
cancelled	When a Job Request is marked as "cancelled" the Requestor has cancelled the Job Request

Category and Descriptive Information

Certain descriptive information is required to create a job — for a complete listing see the API documentation, but some critical properties to be mindful of include:


category	A set of values predefined for a given company that classify the type of job being posted
employer_id	The ID of the Requestor (Employer) requesting the work
request_name	A Requestor-visible name for this Job Request (not visible to Wonoloer)
description	A detailed description of the work to be performed
slots	The number of Wonoloers required. This number must be greater than 0.
venue	The name of the work location, e.g. 'Best Buy Store 321'
start_time	The time to start work in 24-hour format. Example: 2018-08-18 19:30 This must be a date in the future.
duration	The expected length of the Job in minutes. This number must be greater than 0.

Wages

As part of defining a job request you will need to specify whether it is a 1099 or w2 job, and if applicable, what the wage is.

Location Information

As with workers defined through the user service, job requests will be created with longitude and latitude coordinates defined as decimals. These values will be used to help rank workers for the purpose of placement in a given job as well as display the job posting on a map.

Badge Requirements

Badge requirements are sub-attributes of the Job Request and will be used to filter workers when they are not a soft requirement for the job.

Preferred Candidates and Ban Lists

In order to further filter workers for a particular job request, it is possible to specify a list of candidates you would prefer to use if they are available and a list of user ids you specifically do not want assigned to the Job Request.

Example Create Request JSON

Below is an example of a JSON payload necessary to create a job_request.

{
    "job_request": {
        "employer_id": "1234",
        "category": "Wonolo Training Room",
        "venue": "Training Room A",
        "address": "600 Montgomery St",
        "city": "San Francisco",
        "zip": "94111",
        "use_pending_state": false,
        "description": "Wonolo API Training",
        "multi_day": true,
        "multi_day_job_request_id": "2345",
        "notification_distance": 15,
        "start_time": "2019-11-29 08:00:00",
        "request_name": "November 29th 2019 Wonolo API Training",
        "duration": 60,
        "classification": "1099",
        "slots": 1,
        "badge_requirements_attributes": [
            {
                "badge_id": "3456"
            }
        ],
        "open_request": true,
        "state": "posted",
        "ban_list": [
            "6789",
            "6890",
            "6543",
            "6432",
            "6321",
            "5678",
            "5789",
            "7890"
        ]
    }
}

Multi-Day Jobs

Jobs that span multiple days are managed through the Multi-Day Jobs service. A Multi-Day Job joins multiple Job Requests together though a given Job Request’s multi_day_job_request_id property.

This entity specifies frequency (daily or weekly) and the number of repetitions/iteration as you would on a calendar entry.

Additionally, a Requestor may specify that a Wonoloer must accept all days of a Multi-Day Job Request through the same_workers property. Otherwise, a Wonoloer is free to pick and choose those days they wish.

When you are creating a job that spans multiple days, first Create a Multi-day Job Request then use the returned identifier as the multi_day_job_request_id property of the Job Requests you create and set its multi_day property to true,

Webhooks for Job Requests

You may monitor the state of Job Requests by receiving callbacks to your application via Webhooks.

See the this section for information on how to configure you application to use the Wonolo API Webhooks.

Below is an example payload of a job_request state change as it will be sent by Wonolo.

{
    "id": 987654,
    "created_at": "2019-11-07T22:09:40.893-08:00",
    "event": "job_request.state_change",
    "resource": {
        "id": 909090,
        "state": "posted",
        "category": "Training",
        "wage": null,
        "slots": 1,
        "latitude": "37.7952",
        "longitude": "-122.4028",
        "start_time": "2019-11-08T07:00:00.000-08:00",
        "flag_color": "green",
        "duration": 480,
        "venue": "Training Room A",
        "address": "600 Montgomery St",
        "city": "San Francisco",
        "zip": "94111",
        "postal_code": null,
        "country": "US",
        "updated_at": "2019-11-07T22:09:40.854-08:00",
        "description": "Job Number: 12345 \nShift Number: 5678",
        "description_tasks": null,
        "description_company": null,
        "description_travel": null,
        "description_skills": null,
        "description_contact": null,
        "description_arrival": null,
        "employer_id": 2569471,
        "company_id": 1,
        "request_name": "Wonolo Training",
        "multi_day": true,
        "multi_day_job_request_id": 5678,
        "preferred_candidate_ids": [],
        "preferred_wonoloers_info": [],
        "classification": "1099",
        "w2_hourly_rate": "",
        "notification_distance": 75,
        "ban_list": [],
        "push_all_notifications_asap": false,
        "cached_job_states": {},
        "in_white_gloves_period": false,
        "can": null,
        "agent_code": null,
        "organizational_path": null,
        "timezone": "Eastern Time (US & Canada)",
        "re_ranked_worker_ids": null,
        "use_pending_state": true,
        "badge_requirements": [
            {
                "id": 123456,
                "badge_id": 1234,
                "created_at": "2019-11-07T22:09:40.863-08:00",
                "updated_at": "2019-11-07T22:09:40.863-08:00",
                "job_request_id": 7890,
                "badge_name": "API Trainer",
                "badge_icon_url": null,
                "badge_description": "API Trainer"
            }
        ]
    }
}