Build on GrowthPPL.

Authentication

Every call except the index carries an API key in the Authorization header, as a Bearer token. An owner or anyone with the permission to manage API keys creates one in Settings › API & webhooks, choosing its scopes. The full key is shown once; GrowthPPL keeps only a hash of it. Keys start sk_live_. There is no test mode: every key reads and writes your real workspace, so give each one only the scopes it needs. Keys made earlier with an sk_test_ prefix keep working, with the same access. Revoke a key there and it stops working at once.

curl "$GROWTHPPL/api/v1/candidates?stage=interview&limit=50" \
  -H "Authorization: Bearer $GROWTHPPL_KEY"

$GROWTHPPL is the address you sign in to GrowthPPL at. Every key belongs to one workspace, and every call sees only that workspace's data.

Scopes

A key can do only what its scopes allow. An endpoint asks for exactly one scope.

REST endpoints

JSON over HTTPS. A list answers { data: [...], next_cursor }; one record answers { data: {...} }. Responses are never cached.

{
  "data": [
    {
      "id": "…",
      "name": "Asha Thomas",
      "email": "asha@example.com",
      "phone": "",
      "job_id": "…",
      "stage": "interview",
      "status": "active",
      "source": "Careers page",
      "location": "Kochi",
      "skills": [
        "ICU"
      ],
      "score": 0,
      "applied_at": "2026-10-01T04:30:00.000Z",
      "updated_at": "2026-10-03T09:12:00.000Z"
    }
  ],
  "next_cursor": "eyJ0Ijoi…"
}

What each resource returns

Work facts only: never pay, bank details, ID numbers, interview questions or the reasoning behind a score. Employees are read-only.

Pagination

Lists come oldest first, so new rows land at the end. Ask for up to 200 rows with limit (50 if you leave it out). When there are more, next_cursor holds a string to send back as cursor; on the last page it is null. Candidates and employees also take updated_since, an ISO 8601 date-time, to fetch only what changed.

Errors

An error answers with an HTTP status and { error: { code, message } }. The code is stable; the message is for a person to read.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key can't do that. Give it the \"read:hiring\" scope in Settings › API & webhooks."
  }
}

Rate limits

Each key may make 240 REST requests a minute, across every v1 endpoint, and 240 SCIM requests a minute, counted separately. The punch endpoint takes 120 pushes a minute per key. Over the limit, the answer is 429; REST and SCIM add a Retry-After header in seconds.

Webhooks

Add an endpoint in Settings › API & webhooks, choose its events, and copy its signing secret (it starts whsec_). The address must be public and use https. Send test delivers a ping event to that one endpoint.

Every delivery is a POST of one JSON envelope: id, type, created_at and data.

{
  "id": "evt_…",
  "type": "candidate.stage_changed",
  "created_at": "2026-10-03T09:12:00.000Z",
  "data": {
    "candidate": {
      "id": "…",
      "name": "Asha Thomas",
      "email": "asha@example.com",
      "phone": "",
      "stage": "interview",
      "status": "active",
      "source": "Careers page",
      "job_id": "…",
      "job_title": "Staff nurse"
    },
    "stage": "interview"
  }
}

• candidate id, name, email, phone, stage, status, source, job_id, job_title.
• interview id, kind, starts_at, duration_min, where, panel, booked_by.
• employee id, code, name, work_email, title, department, location, start_date, manager_id, status, candidate_id. Work facts only: never pay, bank or ID numbers.

Headers

Delivery and retries

A 2xx answer counts as delivered. Anything else counts as a failed attempt, including a redirect, which is not followed, and no answer after 10 seconds. A failed delivery is tried again after 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours: 6 attempts in all. After 30 failures in a row, the endpoint is paused and the person who added it is told; resume it in Settings › API & webhooks once it is fixed.

Verify a signature

Each delivery carries GrowthPPL-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Compute the HMAC-SHA256 of the timestamp, a full stop and the raw body with your endpoint's secret, compare it in constant time, and refuse a timestamp more than 300 seconds from now. In Node:

const crypto = require("node:crypto");

// rawBody: the request body exactly as received, before JSON.parse.
function verifyGrowthPPL(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Read the body as raw text: a body parsed and serialised again won't match the signature.

SCIM 2.0

Your directory can create, update and deactivate people over SCIM 2.0 at $GROWTHPPL/scim/v2, with an API key that has the scim:provision scope as its bearer token. Users only: GrowthPPL doesn't keep groups. Answers use application/scim+json and SCIM's own error shape.

User attributes

A person created over SCIM is an employee record, and takes a seat on your plan; when no seat is free, the create is refused with 403. Deactivating never deletes anyone.

Attendance punches

The answer lists inserted, duplicates, daysRebuilt, unknownCodes, closed. A punch on a day a paid payroll run has closed is not written; it comes back in closed with the reason. When nothing could be written because no code is mapped or every day is closed, the status is 422. Errors here answer { error: message }.

Job feeds

Only live, publicly visible roles, newest first, up to 500. Each role applies through your own form, and the applicant's source is recorded as the board. Boards may cache a feed for up to 15 minutes.

API changes

v1 is the only version. Changes to it are listed here, newest first.

• 18 Oct 2026. Keys can no longer be given the write:people or read:analytics scopes, which no endpoint checks. A key that already carries one keeps working.
• 06 Oct 2026. REST API v1 (jobs, candidates, employees), signed webhooks, SCIM 2.0 Users and XML job feeds.
• 31 Aug 2026. The punch ingest endpoint for attendance devices.

Everything GrowthPPL connects to →