Skip to main content
This guide walks through adding a contractor to Plane via the API—from creating the worker to monitoring their onboarding progress.

​
Prerequisites

​
Create the worker

Start by creating a worker with type set to contractor: 
curl -X POST https://api.plane.com/v1/workers \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contractor",
    "name": {
      "first": "Jordan",
      "last": "Lee"
    },
    "email": "jordan@example.com",
    "title": "Backend Engineer"
  }'
Response
{
  "id": "wr_abc123"
}
When you create the worker, Plane automatically:
  • Sends the contractor an invitation email
  • Starts the onboarding flow with the right tasks for their type and location
  • Creates the appropriate agreement for signature

​
Retrieve the worker

Fetch the full worker object to see their current state: 
curl https://api.plane.com/v1/workers/wr_abc123 \
  -u "YOUR_API_KEY:"
The worker object includes their employment, compensation, and onboarding status.

​
Monitor onboarding with webhooks

Rather than polling the API, set up webhooks to get notified as the contractor completes onboarding steps. Key events to listen for:
  • worker.updated—the worker’s profile or status changed
  • document.signed—an agreement or document was signed
Webhook handler example
import { Webhook } from "svix";

const wh = new Webhook("whsec_your_signing_secret");

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = wh.verify(req.body, {
      "svix-id": req.headers["svix-id"],
      "svix-timestamp": req.headers["svix-timestamp"],
      "svix-signature": req.headers["svix-signature"],
    });

    switch (event.type) {
      case "worker.updated":
        console.log(`Worker ${event.data.id} updated`);
        break;
      case "document.signed":
        console.log(`Document signed for worker ${event.data.worker}`);
        break;
    }

    res.status(200).send("OK");
  } catch (err) {
    res.status(400).send("Invalid signature");
  }
});
See Setting up webhooks for full verification details and examples in other languages.

​
What happens next

After you create the contractor:
  1. The contractor receives an email inviting them to Plane.
  2. They complete their tasks—signing the agreement, providing tax documents, and adding bank details.
  3. You complete admin tasks—setting compensation and any additional details.
  4. The contractor becomes active and is ready for payments.
You can track progress from the worker’s profile in the dashboard, or by fetching the worker through the API.

​
Next steps

Send a payment

Once your contractor is active, send them a payment.

Workers API

Full reference for the workers resource.