The Wonolo API (V2.0) is a RESTful API to perform CRUD operations on Wonolo platform resources.

Currently, JSON is the only encoding format supported.

API Keys

Use of the Wonolo API requires keys.

Test and Production Environments

You will be issued with two sets of API keys:

Security / HTTPS

All API calls must be made over HTTPS.

With the exception of /authenticate and /info, all API calls must use an authorization token (passed as the token parameter).


Webhooks allow your system to be notified of changes to certain Wonolo resources via an HTTP call initiated from the Wonolo platform.

Currently, webhooks are available for state changes to JobRequest and Job resources.

Webhook Security

Webhooks are authenticated using a X-Wonolo-Webhook-Token HTTP header. This header is set to a SHA256 digest of the webhook's JSON body concatenated with your secret API key.

Configuring Webhooks

To enable webhooks, please first obtain your API keys and then contact us.

Access Control / Priviledge Levels

Wonolo API keys will provide one of two different levels of access to Wonolo resources:

  • Public Pool access - if you are accessing Wonolo's public pool of Wonoloers

  • Private Pool access - if your company is managing its own private pool of workers

With Public Pool access, you will only be able to access those Wonoloers you have active Jobs with, and Job Requests and Jobs that you have created. Also, write operations (update/PATCH and create/POST) are forbidden in many cases.

For more details, consult the documentation of the individual endpoints.

Getting Started

Once you receive your API keys, the first step is to authenticate to obtain a token for use with subsequent API calls. Please refer to the /api_v2/authenticate endpoint documentation below.


A qualification or skill that is required to accept a particular Job Request

Resource Description
GET /api_v2/badges List available Badges
GET /api_v2/badges/:id Get a specific Badge
POST /api_v2/badges Create a new Badge
PATCH /api_v2/badges/:id Update a Badge
DELETE /api_v2/badges/:id Delete a Badge


Resource Description
GET /api_v2/customers List Customers belonging to a Company
GET /api_v2/customers/:id Get a specific Customer
POST /api_v2/customers Create a Customer
PUT/PATCH /api_v2/customers/:id Update a Customer
GET /api_v2/customers/exists Check for existing of Customer by name


Resource Description
GET /api_v2/info Get API information

Job requests
A request for Wonoloers to perform a Job

Resource Description
GET /api_v2/job_requests List JobRequests
POST /api_v2/job_requests Create a JobRequest
PATCH /api_v2/job_requests/:id Update a JobRequest
GET /api_v2/job_requests/:id Get a specific JobRequest
GET /api_v2/job_requests/:id/rankings List the Wonoloers that are ranked for this JobRequest
POST /api_v2/job_requests/:id/resend_notifications Resend notifications for this JobRequest
POST /api_v2/job_requests/:id/re_rank_workers Re-rank workers for this JobRequest

A Wonoloer performing a Job Request

Resource Description
GET /api_v2/jobs List Jobs
POST /api_v2/jobs Create a Job
POST /api_v2/jobs/assign Assign a Job
PATCH /api_v2/jobs/:id Update a Job
GET /api_v2/jobs/:id Get a specific Job

An In-app Message between a Requestor and a Wonoloer

Resource Description
GET /api_v2/messages List Messages
POST /api_v2/messages Create a Message
GET /api_v2/messages/:id Get a specific Message

Multi day job requests
A Job Request that spans multiple days.

Resource Description
POST /api_v2/multi_day_job_requests Create a Multi-day Job Request
PATCH /api_v2/multi_day_job_requests/:id Update a Multi-day Job Request
GET /api_v2/multi_day_job_requests/:id Get a specific Multi-day Job Request

Search Wonolo models

Resource Description
GET /api_v2/search Search Wonolo


Resource Description
POST /api_v2/authenticate Authenticate and obtain a token

Users - Wonoloers and Requestors

Resource Description
GET /api_v2/users List users
POST /api_v2/users Create a user
POST /api_v2/users/invite Invite worker into our system
PUT/PATCH /api_v2/users/:id Update a user
GET /api_v2/users/:id Get a specific user
GET /api_v2/users/:id/tracking Get tracking data for a specific user
POST /api_v2/sync_auth_token sync auth_token for external user