API Documentation | Picoworkers

Picoworkers' API Documentation

Last updated at November 3, 2021

Overview
Authentication
Jobs
Users
- Get Balances
Lists
- Add workers
Wallet
- Depositnew

1. Overview

Picoworkers API is a JSON based API where employers can create jobs programatically.
It’s currently in Beta and all feedback and suggestions are appreciated.

If you have deposited over $1,000 in crypto, please message support for auto approval posts. Others considered on a case by case basis.

The base endpoint for all requests is https://picoworkers.com/api/

2. Authentication

Every API request needs to be authenticated. You can create or reset you API secret in the tab SETTINGS of your Account Settings page.

To sign requests, add the header Authorization with the value of 'Basic ' + the base 64 encoding of your USER_ID and API_SECRET separated by colon

Example:

1. Generate the base64 encoding of your user_id and api_secret

        php> echo base64_encode('user_id:api_secret');
        php> dXNlcl9pZDphcGlfc2VjcmV0

2. Send the header Authorization in the request

        $ curl -H 'Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0' \
        https://picoworkers.com/api/jobs/get-zones.php

3. Jobs

In order to create jobs, you need to inform the zone_id and excluded_countries, if any, OR the list_id, if it's a job targeted to one of your list of workers, and the category_id.

The most updated information can be obtained using the zones, lists and categories endpoints. Refer to those endpoints to set up the job correctly.

3.1 Zones Endpoint

Get the available zones and the list of countries that can be excluded from a zone.

        GET https://picoworkers.com/api/jobs/get-zones.php

Example request

        GET /api/jobs/get-zones.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0

Example response

        [
          {
            "id": "africa1",
            "zone": "Africa",
            "excludable_countries": [ "ao", "bw", "cg", "eg", "et", "gh", "ke", "ly", "ma", "mz", "ng", "rw", "za", "tz", "ug", "zw", "tn" ]
          },
          {
            "id": "asia1",
            "zone": "Asia",
            "excludable_countries": [ "bd", "cn", "in", "id", "jp", "kr", "lk", "my", "pk", "ph", "sg", "th", "vn" ]
          },
          {
            "id": "europe1",
            "zone": "Europe West",
            "excludable_countries": [ "at", "be", "ch", "de", "dk", "es", "fi", "fr", "uk", "ie", "is", "it", "lu", "mc", "no", "pt", "se", "sm" ]
          },
          {
            "id": "europe2",
            "zone": "Europe East",
            "excludable_countries": [ "al", "am", "by", "ba", "bg", "cy", "cz", "ee", "gr", "hu", "hr", "lt", "mk", "mt", "rs", "ru", "si", "sk", "tr", "ua", "pl", "ro" ]
          },
          {
            "id": "int",
            "zone": "International",
            "excludable_countries": [ "al", "pk", "bd", "id", "in", "ph", "ro", "eg", "pl", "my", "np", "vn", "cn", "lt", "ma", "us", "ca", "uk", "au", "de", "fr", "lk", "si", "ve", "co" ]
          },
          {
            "id": "latin",
            "zone": "Latin America",
            "excludable_countries": [ "ar", "bo", "br", "cl", "co", "ec", "fk", "gf", "gy", "mx", "py", "pe", "sr", "uy", "ve" ]
          },
          {
            "id": "muslim",
            "zone": "Muslim countries",
            "excludable_countries": [ "dz", "id", "in", "pk", "bd", "ma", "ng", "eg", "ir", "tr", "tn" ]
          },
          {
            "id": "west1",
            "zone": "USA & Western",
            "excludable_countries": [ "us", "uk", "ca", "au", "nz" ]
          }
        ]

3.2 Lists Endpoint

Get the available lists of workers created in the tab Emp. Lists of your Account Settings.
Picoworkers requires at least 10 workers to run a job posted using the API. Only lists with 10 workers or more will be accepted.

        GET https://picoworkers.com/api/jobs/get-lists.php

Example request

        GET /api/jobs/get-lists.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0

Example response

        [
          {
            "id": 12870,
            "name": "Successfully Completed",
            "workers": 147
          },
          {
            "id": 14118,
            "name": "Awesome workers",
            "workers": 102
          },
          {
            "id": 14256,
            "name": "Workers from Brazil",
            "workers": 53
          },
          {
            "id": 16329,
            "name": "My special list",
            "workers": 18
          }
        ]

3.3 Categories Endpoint

Get the list of categories and the minimum payment per task you must set to run the job.
For a list job, please use the international zone pricing as the minimum payment per task.

        GET https://picoworkers.com/api/jobs/get-categories.php

Example request

        GET /api/jobs/get-categories.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0

Example response

        [
          {
            "id": "0500",
            "category": "Sign up",
            "subcategory": "Email submit only",
            "min_task_value": {
              "int": "0.080",
              "west1": "0.240",
              "europe1": "0.200",
              "europe2": "0.160",
              "asia1": "0.100",
              "africa1": "0.100",
              "latin": "0.100",
              "muslim": "0.100"
            }
          },
          {
            "id": "0501",
            "category": "Sign up",
            "subcategory": "Simple Sign up",
            "min_task_value": {
              "int": "0.080",
              "west1": "0.240",
              "europe1": "0.200",
              "europe2": "0.160",
              "asia1": "0.100",
              "africa1": "0.100",
              "latin": "0.100",
              "muslim": "0.100"
            }
          },

          ...

          {
            "id": "9002",
            "category": "Surveys / Offers",
            "subcategory": "Up to 50 questions",
            "min_task_value": {
              "int": "0.500",
              "west1": "1.200",
              "europe1": "1.000",
              "europe2": "0.800",
              "asia1": "0.600",
              "africa1": "0.600",
              "latin": "0.600",
              "muslim": "0.600"
            }
          },
          {
            "id": "9900",
            "category": "Other",
            "subcategory": "Describe and set acceptable price",
            "min_task_value": {
              "int": "0.050",
              "west1": "0.150",
              "europe1": "0.130",
              "europe2": "0.100",
              "asia1": "0.060",
              "africa1": "0.060",
              "latin": "0.060",
              "muslim": "0.060"
            }
          }
        ]

3.4 Post Job

Post a new job.

        POST https://picoworkers.com/api/jobs/post-job.php

Example request

        POST /api/jobs/post-job.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "zone_id": "int",
          "category_id": "0501",
          "title": "Sign up to ACME website",
          "instructions": [
              "visit the ACME website",
              "Create an account"
          ],
          "proofs": [
              {
                  "description": "Screenshot of your profile at ACME website",
                  "type": "screenshot"
              }
          ],
          "num_tasks": 25,
          "task_value": 0.10,
          "speed": 1000,
          "ttr": 7,
          "hold_time": 15
        }

The following attributes are available:

Attribute Type Required? Default Description

test integer no 0 Set this attribute 1 if you are in development. The job will be validated but it will not be created. No costs will be charged from your spendable balance.

zone_id string yes — Zone ID to publish the job. Conditionally required: zone_id or list_id is required to run the job. Use the zones and/or lists endpoints to get the list of zones and/or employer lists.

excluded_countries string array no — List of countries codes to be excluded from the target zone. Use the zones endpoint to get a list of excludable countries for each zone.

list_id int yes — List ID to publish the job. Conditionally required: zone_id or list_id is required to run the job. Use the zones and/or lists endpoints to get the list of zones and/or employer lists.

category_id string yes — Category ID to publish the job. Use the categories endpoint to get the list of available categories. The category ID must be exactly what is returned in the category endpoint, respecting the leading zeroes that may exist.

title string yes — Job title.

notes string no — Additional work notes for workers.

instructions string array no — List of instructions of expected work from workers. Example: ["Visit website ABC", "Click the sidebar banner."]

proofs

object array

—

Nested object with the following attributes. A max of 4 proofs can be required.

Attribute	Type	Required?	Default	Description
`type`	string	yes	—	Proof type. Possible values are text and screenshot.
`description`	string	yes	—	Proof description. What is required from workers to prove they have completed the task.

challenges

object array

—

Nested object with the following attributes. A max of 3 challenges can be set up.

Attribute	Type	Required?	Default	Description
`question`	string	yes	—	Challenge question that will be displayed to users.
`answer`	string	yes	—	The correct answer to the challenge question to be verified against the answer from workers.

challenge_action string no — Action to be taken when worker answer the challenge incorrectly. Posiible values are rate_nok, to rate the task as Not Satisfied, and rate_nok_block, to rate the task as Not Satisfied and block the worker from future jobs. Required if there are challenges set up.

num_tasks int no — Number of tasks to be performed by workers. Minimum of 10 tasks is required.

workers_level string no starter Target a minimum level of workers. Possible values are "starter", "expert" and "advanced".

workers_max_tasks int no 1 Number of tasks that the same worker can submit. It can range from 1 to 10. For greater than 1, the workers_level must not be "starter".

task_value float yes — Amount each worker will earn if the task is rated as Satisfied.

speed int no 1000 Speed which the job is displayed to workers. From 1-1000 (1 is slow, 1000 is fast-normal. Each page refresh generates a random number. All job speed setting numbers above this random number are shown. A speed of 10 or even 100, the probability of showing up is really low.)

ttr int no 7 Number of days the employer has to rate the task before it is auto rated as Satisfied by the system. It ranges from 1 to 7 days

autorate string no NO Used to let the system auto rate tasks based on the PCODE submitted by the workers. Possible values are NO, where the system will not do anything and all rating will be left for the employer. V, where the system will verify if the worker has submitted the correct PCODE but will not rate the task. V+R, where the system will verify and auto rate the task as Satisfied if the worker submitted the correct PCODE. To learn more about PCODE, visit Auto-rating with PCODE

pause_after_approval int no 0 Used to immediately pause the job after it's approved. Possible values are 0, to not pause it and 1, to pause it.

hold_time int no 5 The number of minutes a worker can hold a position before submitting the task. It range from 5 to 30.

Example response

        {
          "ok": true,
          "url": "https://picoworkers.com/employer/campaign-details.php?Id=JOB_ID",
          "message": "Job posted successfully"
        }

3.5 Add Positions

Add positions

        POST https://picoworkers.com/api/jobs/add-positions.php

Example request

        POST /api/jobs/add-positions.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "job_id": "fc7b3bd10d08",
          "positions": 1
        }

The following attributes are available:

Attribute	Type	Required?	Default	Description
`job_id`	string	yes	—	Id of the job you want to add positions.
`positions`	int	yes	—	Number of positions to add in that job. From 1 to 9999.

Example response

        {
          "ok": true,
          "message": "The position(s) has been added."
        }

3.6 Set Speed

Set the job speed.

        POST https://picoworkers.com/api/jobs/set-speed.php

Example request

        POST /api/jobs/set-speed.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "job_id": "fc7b3bd10d08",
          "speed": 800
        }

The following attributes are available:

Attribute	Type	Required?	Default	Description
`job_id`	string	yes	—	Id of the job you want to set the new speed.
`speed`	int	yes	1000	Speed of the job. From 1 to 1000.

Example response

        {
          "ok": true,
          "message": "Job speed updated successfully."
        }

3.7 Set TTR

Set the job time to rate.

        POST https://picoworkers.com/api/jobs/set-ttr.php

Example request

        POST /api/jobs/set-ttr.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "job_id": "fc7b3bd10d08",
          "ttr": 3
        }

The following attributes are available:

Attribute	Type	Required?	Default	Description
`job_id`	string	yes	—	Id of the job you want to set the new TTR.
`ttr`	int	yes	7	Time to rate of the job. From 1 to 7.

Example response

        {
          "ok": true,
          "message": "Job time to rate (TTR) updated successfully."
        }

3.8 Get Jobs

Get your active jobs. Archived jobs will not be retrieved. Make sure to iterate through all pages to get all the jobs.

        GET https://picoworkers.com/api/jobs/get-jobs.php

Example request

        GET /api/jobs/get-jobs.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0

The following fields can be added in the query string:

Attribute	Type	Required?	Default	Description
`page`	int	no	1	The page of jobs you want to retrieve.
`status`	string	no	—	You can filter the retrieved jobs by status. Possible values are: running, finished, pending_review, pending_restart, paused, paused_system, paused_admin, blocked, declined

Example response

        {
          "current_page": 1,
          "pages": 1,
          "jobs": [
            {
              "id": "0950e7d99b65",
              "id_user": "abcd1234",
              "zone_id": "int",
              "excluded_countries": [],
              "category_id": "2004",
              "created_at": "2021-10-25T07:42:35Z",
              "status": "RUNNING",
              "task_value": 0.06,
              "tasks_done": 3741,
              "num_tasks": 4030,
              "workers_max_tasks": 1,
              "workers_level": "starter",
              "speed": 1000,
              "ttr": 7,
              "autorate": "NO",
              "pause_after_approval": 0,
              "hold_time": 5,
              "title": "Play Video",
              "instructions": [
                "Go to https://video-website.io/watch/1",
                "Play the video."
              ],
              "notes": "",
              "proofs": [
                {
                  "description": "FULL screenshot showing video is playing.",
                  "type": "screenshot"
                }
              ],
              "challenge_action": "",
              "challenges": []
            }
          ]
        }

3.9 Get Unrated Tasks

Get the unrated tasks of a specific job or all jobs. Make sure to iterate through all pages to get all the tasks.

        GET https://picoworkers.com/api/jobs/get-unrated-tasks.php

Example request

        GET /api/jobs/get-unrated-tasks.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0

The following fields can be added in the query string:

Attribute	Type	Required?	Default	Description
`page`	int	no	1	The page of tasks you want to retrieve.
`job_id`	string	no	—	Get the unrated tasks of a specific job. If empty, the unrated tasks of all your jobs will be retrieved.

Example response

        {
          "current_page": 1,
          "pages": 1,
          "tasks": [
            {
              "id": "158004285a3523",
              "job_id": "abcdef123456",
              "worker_id": "abcd1234",
              "finished_at": "2021-11-01T17:04:45Z",
              "ip_address": "127.0.0.1",
              "country_code": "XX",
              "revision_number": 0,
              "variables": [],
              "proofs": [
                {
                  "text": "submitted proof"
                }
              ]
            }
          ]
        }

3.10 Rate Single Task

Rate a task.

        POST https://picoworkers.com/api/jobs/rate-single-task.php

Example request

        POST /api/jobs/rate-single-task.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "job_id": "fc7b3bd10d08",
          "task_id": "1416896140ecb7",
          "task_rating": "ok",
          "task_satisfaction": "good",
          "task_comment": "great job!",
          "list_id": 0,
          "block_worker": false,
          "task_bonus": 0.0
        }

The following fields can be added in the query string:

Attribute	Type	Required?	Default	Description
`task_id`	string	yes	—	Id of the task to be rated.
`job_id`	string	yes	—	Id of the Job.
`task_rating`	string	yes	—	Task rating. Possible values are: ok, not_ok, revise
`task_satisfaction`	string	no	—	Your satisfaction with the task. Possible values are: excellent, good, ok (if rating is ok), or: incorrect, spam, dupe (if rating is not_ok)
`task_comment`	string	no	—	Task comments. Required if task_rating is not_ok or revise
`list_id`	int	no	0	Inform the id of a custom list in case you want to add the worker to it.
`block_worker`	boolean	no	false	Worker should be blocked?
`task_bonus`	float	no	0.0	Bonus amount to be sent to the worker.

Example response

        {
          "ok": true,
          "message": "Task rated successfully."
        }

4. Users

Get information about your user.

4.1 Balances Endpoint

Get the balances from your user.

        GET https://picoworkers.com/api/users/get-balances.php

Example request

        GET /api/users/get-balances.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

Example response

        {
          "earned": "0.4200",
          "spendable": "3.3482"
        }

5. Lists

Manage your custom lists.

5.1 Add Workers

Add one or more workers to a custom list. Invalid and blocked workers will not be added.

        POST https://picoworkers.com/api/lists/add-workers.php

Example request

        POST /api/lists/add-workers.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "list_id": 15237,
          "workers": ["0de178af", "ffcc1278", "abcd0129"]
        }

The following attributes are available:

Attribute	Type	Required?	Default	Description
`list_id`	int	yes	—	Id of the list you want to add the workers.
`workers`	string array	yes	—	List of worker ids to be added to the custom list.

Example response

        {
          "ok": true,
          "message": "Workers added to the list successfully."
        }

6. Wallet

Manage your wallet.

6.1 Deposit

Add funds to your account. Only available for Credit Card payments. To use this API, please enable it first in Account Settings page.

        POST https://picoworkers.com/api/wallet/deposit.php

Example request

        POST /api/wallet/deposit.php HTTP/1.1
        Host: picoworkers.com
        Authorization: Basic dXNlcl9pZDphcGlfc2VjcmV0
        Content-Type: application/json

        {
          "amount": 1000
        }

The following attributes are available:

Attribute	Type	Required?	Default	Description
`amount`	int	yes	—	Desired amount in cents (USD) to deposit. Minimum amount is 1000 ($10)

Example response

        {
          "ok": true,
          "message": "Thank you for your deposit! Your account balance will be updated shortly."
        }

Picoworkers' API Documentation

Contents

1. Overview

2. Authentication

3. Jobs

3.1 Zones Endpoint

3.2 Lists Endpoint

3.3 Categories Endpoint

3.4 Post Job

3.5 Add Positions

3.6 Set Speed

3.7 Set TTR

3.8 Get Jobs

3.9 Get Unrated Tasks

3.10 Rate Single Task

4. Users

4.1 Balances Endpoint

5. Lists

5.1 Add Workers

6. Wallet

6.1 Deposit