Skip to main content
This guide walks you through setting up API access and making your first request. By the end, you will have a working sandbox environment and a test worker created through the API.

​
Prerequisites

  • A Plane account with admin access
  • An API key (or you will create one below)

​
Create a sandbox

Before testing with the API, create a sandbox so you can experiment without affecting live data.
1

Go to Developers

In your Plane dashboard, navigate to Developers in the sidebar, then click Sandboxes.
2

Create a sandbox

Click Create sandbox and confirm. You will start with an empty workspace for testing.
3

Enter the sandbox and create an API key

Click Enter on your new sandbox, then go to Developers > API keys and click Create secret key. Copy the key—it is only shown once.
Your sandbox key starts with sk_test_. Make sure you are using this key for testing, not a live key (sk_live_).

​
Make your first request

List the workers in your sandbox. Since it is new, the result will be empty—but this confirms your authentication is working.
The Plane API accepts both HTTP Basic Auth (-u YOUR_KEY:) and Bearer tokens (Authorization: Bearer YOUR_KEY). The examples below use whichever is most idiomatic for each language. See Authentication for details.
curl https://api.plane.com/v1/workers \
  -u "sk_test_YOUR_KEY_HERE:"
You should see an empty list response: 
{
  "data": []
}

​
Create a test worker

Now create a contractor in your sandbox: 
curl -X POST https://api.plane.com/v1/workers \
  -u "sk_test_YOUR_KEY_HERE:" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contractor",
    "name": {
      "first": "Alex",
      "last": "Rivera"
    },
    "email": "alex@example.com",
    "title": "Design Consultant"
  }'
The response includes the new worker’s ID: 
{
  "id": "wr_test_abc123"
}
Sandbox records use a _test_ midfix in their IDs, making it easy to distinguish test data from live data.

​
Retrieve the worker

Use the returned ID to fetch the full worker object: 
curl https://api.plane.com/v1/workers/wr_test_abc123 \
  -u "sk_test_YOUR_KEY_HERE:"

​
Next steps

You have authenticated, created a sandbox, and made your first API calls. From here:

Onboard a contractor

Walk through the full contractor onboarding flow via the API.

Send a payment

Send a one-off payment to a worker.

Set up webhooks

Get real-time notifications when things happen in Plane.

API reference

Browse every endpoint and object in the API.