> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard a contractor

> Add a contractor to Plane and start their onboarding flow using the API.

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

## Prerequisites

* A Plane API key ([set up authentication](/reference/authentication))
* A [sandbox](/reference/sandboxes) for testing (recommended)

## Create the worker

Start by creating a worker with `type` set to `contractor`:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.plane.com/v1/workers", {
    method: "POST",
    headers: {
      Authorization: `Bearer YOUR_API_KEY`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "contractor",
      name: { first: "Jordan", last: "Lee" },
      email: "jordan@example.com",
      title: "Backend Engineer",
    }),
  });

  const { id } = await response.json();
  console.log("Worker created:", id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.plane.com/v1/workers",
      auth=("YOUR_API_KEY", ""),
      json={
          "type": "contractor",
          "name": {"first": "Jordan", "last": "Lee"},
          "email": "jordan@example.com",
          "title": "Backend Engineer",
      },
  )

  worker = response.json()
  print("Worker created:", worker["id"])
  ```
</CodeGroup>

```json Response theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.plane.com/v1/workers/wr_abc123 \
    -u "YOUR_API_KEY:"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.plane.com/v1/workers/wr_abc123",
    {
      headers: { Authorization: `Bearer YOUR_API_KEY` },
    }
  );

  const worker = await response.json();
  console.log(worker);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.plane.com/v1/workers/wr_abc123",
      auth=("YOUR_API_KEY", ""),
  )

  print(response.json())
  ```
</CodeGroup>

The worker object includes their employment, compensation, and onboarding status.

## Monitor onboarding with webhooks

Rather than polling the API, set up [webhooks](/guides/setting-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

```javascript Webhook handler example theme={null}
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](/guides/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

<CardGroup cols={2}>
  <Card title="Send a payment" icon="paper-plane" href="/guides/send-a-payment">
    Once your contractor is active, send them a payment.
  </Card>

  <Card title="Workers API" icon="book" href="/reference/workers/object">
    Full reference for the workers resource.
  </Card>
</CardGroup>