API reference.

Quickstart #

Three steps. A sandbox key, your first call, a walk through the response shape. The same fields in the same positions you will see in production.

1. Get a key

Sign in, open the dashboard, click Create key. Choose sk_test_ for sandbox or pk_live_ for production reads. The plaintext is shown once. Save it to your secrets manager.

2. Make your first request

List the most recent jobs at a single firm.

curl https://api.placement.solutions/v1/jobs?firm_id=frm_kirkland&limit=10 \
  -H "Authorization: Bearer pk_live_REPLACE_ME"

import requests

resp = requests.get(
    "https://api.placement.solutions/v1/jobs",
    params={"firm_id": "frm_kirkland", "limit": 10},
    headers={"Authorization": "Bearer pk_live_REPLACE_ME"},
    timeout=10,
)
resp.raise_for_status()
for job in resp.json()["data"]:
    print(job["id"], job["title"])

const resp = await fetch(
  "https://api.placement.solutions/v1/jobs?firm_id=frm_kirkland&limit=10",
  { headers: { "Authorization": "Bearer pk_live_REPLACE_ME" } }
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const { data } = await resp.json();
for (const job of data) console.log(job.id, job.title);

3. Read the response

{
  "data": [
    {
      "id": "job_01J9X5AC2P3K8Q4N7M6Y3R2T1V",
      "firm_id": "frm_kirkland",
      "title": "Capital Markets Associate",
      "location": "New York, NY",
      "practice_area": "capital-markets",
      "seniority": "associate",
      "is_remote": false,
      "salary_min": 225000,
      "salary_max": 365000,
      "posted_at": "2026-05-04T09:14:22Z",
      "url": "https://api.placement.solutions/jobs/job_01J9X5AC2P3K8Q4N7M6Y3R2T1V/capital-markets-associate"
    }
  ],
  "next_cursor": "eyJsYXN0X2lkIjoiam9iXzAxSjlYNUFDLi4uIn0",
  "has_more": true
}

You now have the request shape, the error envelope (covered next), and the cursor pagination contract. From here, every endpoint follows the same patterns.

Authentication #

Every request must carry an Authorization: Bearer <key> header. Keys self-identify by prefix.

Create a key

curl -X POST https://api.placement.solutions/v1/me/keys \
  -H "Authorization: Bearer sk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "pk_live_",
    "scopes": ["jobs:read", "firms:read"],
    "ip_allowlist": ["203.0.113.0/24"]
  }'

import requests
resp = requests.post(
    "https://api.placement.solutions/v1/me/keys",
    headers={"Authorization": "Bearer sk_live_REPLACE_ME"},
    json={"prefix": "pk_live_", "scopes": ["jobs:read", "firms:read"], "ip_allowlist": ["203.0.113.0/24"]},
)
key = resp.json()["key"]  # SAVE NOW. Will not be shown again.

IP allowlist

Each key can be locked to one or more IPv4, IPv6, or CIDR ranges. Calls from outside the allowlist return ip_not_allowed. Leave the allowlist empty to accept any source IP. We strongly recommend setting it on every pk_live_ key in production.

Rotation

Create the new key first, swap it into your application, then revoke the old one. There is no "rotate in place" operation; key creation and revocation are atomic and independent. Keys carry a last_used_at timestamp so you can confirm cutover before revoking.

Error envelope #

Every non-2xx response uses the same shape:

{
  "error": {
    "code": "rate_limited",
    "message": "You have exceeded your monthly call quota. Resets 2026-06-01.",
    "request_id": "req_01J9X5AC2P3K8Q4N7M6Y3R2T1V",
    "doc_url": "https://api.placement.solutions/api-reference#err-rate_limited"
  }
}

Always log request_id on errors. When you contact support, that is the first thing we ask for.

Code reference

Twenty-four named codes. The retry column tells you whether a retry with the same input could succeed: yes means a transient condition that may resolve, cond means retry only after fixing the request, no means do not retry without operator action.

Example: 429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Sustained rate exceeded. Try again in 28 seconds.",
    "request_id": "req_01J9X5BC4Q5M0R6P9N8Z5T4U3X",
    "doc_url": "https://api.placement.solutions/api-reference#err-rate_limited"
  }
}

Cursor pagination #

Every list endpoint paginates with opaque cursors. Pass cursor and limit on the request; the response includes next_cursor until the page set is exhausted.

• limit — integer 1–500. Default 100. Maximum 500.
• cursor — opaque base64. Echo it back unchanged on the next call.
• next_cursor — present in the response while more pages exist. Absent on the final page.
• has_more — boolean. Always present.

Worked example: walk every recent lateral move

# first page
curl "https://api.placement.solutions/v1/lateral-moves?since=2026-04-01&limit=200" \
  -H "Authorization: Bearer pk_live_REPLACE_ME"

# second page (echo next_cursor from the first response)
curl "https://api.placement.solutions/v1/lateral-moves?since=2026-04-01&limit=200&cursor=eyJsYXN0X2lkIjoibG1fMDFKOVg1Li4uIn0" \
  -H "Authorization: Bearer pk_live_REPLACE_ME"

import requests

def walk(url, params, headers):
    cursor = None
    while True:
        p = {**params, "limit": 500}
        if cursor: p["cursor"] = cursor
        r = requests.get(url, params=p, headers=headers, timeout=10)
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        if not body.get("has_more"):
            return
        cursor = body["next_cursor"]

for move in walk(
    "https://api.placement.solutions/v1/lateral-moves",
    {"since": "2026-04-01"},
    {"Authorization": "Bearer pk_live_REPLACE_ME"},
):
    print(move["id"], move["to_firm_id"])

Rate limits #

Two ceilings. A sustained per-minute rate that protects the platform. A monthly quota that meters your tier. The first signals back-off; the second signals upgrade.

Headers on every response

When you cross either ceiling, the response is 429 with the rate_limited envelope. Honor Retry-After. A monthly-quota 429 also includes a message field that names the cycle reset date.

See pricing and tier details for full feature breakdown, FAQ, and contract options.

Idempotency #

Every POST endpoint accepts an Idempotency-Key header. We dedupe within a 24-hour window. If you replay the exact same request body with the same key inside the window, we return the original response and skip side effects. If the body differs from the original, we return idempotency_key_conflict.

Header contract

• Up to 255 characters. Letters, digits, hyphens. UUID v4 is recommended.
• Window is 24 hours from first observation.
• One key per logical operation. Reusing the same key for two different writes is the bug we are protecting you against.

Worked example

curl -X POST https://api.placement.solutions/v1/exports \
  -H "Authorization: Bearer pk_live_REPLACE_ME" \
  -H "Idempotency-Key: 6e9d1f4c-2a4b-4f2e-9a1c-93b7d2c4e5f6" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "lateral_moves", "filters": {"since": "2026-01-01"}, "format": "csv" }'

import requests, uuid
key = str(uuid.uuid4())
def submit():
    return requests.post(
        "https://api.placement.solutions/v1/exports",
        headers={
            "Authorization": "Bearer pk_live_REPLACE_ME",
            "Idempotency-Key": key,
        },
        json={"kind": "lateral_moves", "filters": {"since": "2026-01-01"}, "format": "csv"},
    )
# Safe to retry on network error; the second call returns the original response.
resp = submit()

Versioning #

Major versions live in the URL. The current version is v1. We do not use header-based versioning.

What can change without notice

• New endpoints.
• New optional query parameters.
• New fields on existing response objects (clients must ignore unknown fields).
• New enum values on existing fields.
• New event types on webhooks.

What gives six months of notice

• Removing or renaming an endpoint.
• Removing or renaming a response field.
• Tightening a query parameter (changing default, narrowing accepted values).
• Removing an enum value.

Deprecated endpoints respond with 299 Deprecated in addition to their normal 2xx, plus a Sunset header carrying the cutover date and a Link header pointing at the migration guide. The changelog is the source of truth.

List jobs #

curl "https://api.placement.solutions/v1/jobs?practice_area=private-equity&market=new-york&limit=50" \
  -H "Authorization: Bearer pk_live_REPLACE_ME"

requests.get("https://api.placement.solutions/v1/jobs",
    params={"practice_area": "private-equity", "market": "new-york", "limit": 50},
    headers={"Authorization": "Bearer pk_live_REPLACE_ME"}).json()

await fetch("https://api.placement.solutions/v1/jobs?practice_area=private-equity&market=new-york&limit=50",
  { headers: { "Authorization": "Bearer pk_live_REPLACE_ME" } }).then(r => r.json());

Retrieve a job #

curl https://api.placement.solutions/v1/jobs/job_01J9X5AC2P3K8Q4N7M6Y3R2T1V \
  -H "Authorization: Bearer pk_live_REPLACE_ME"

requests.get("https://api.placement.solutions/v1/jobs/job_01J9X5AC2P3K8Q4N7M6Y3R2T1V",
    headers={"Authorization": "Bearer pk_live_REPLACE_ME"}).json()

await fetch("https://api.placement.solutions/v1/jobs/job_01J9X5AC2P3K8Q4N7M6Y3R2T1V",
  { headers: { "Authorization": "Bearer pk_live_REPLACE_ME" } }).then(r => r.json());

List firms #

Retrieve a firm #

{
  "id": "frm_kirkland",
  "name": "Kirkland & Ellis",
  "amlaw_tier": "amlaw_50",
  "headcount_total": 3402,
  "partner_count": 1198,
  "practice_mix": [
    {"slug": "private-equity",   "share": 0.31},
    {"slug": "litigation",       "share": 0.24},
    {"slug": "restructuring",    "share": 0.11}
  ],
  "offices": ["new-york", "chicago", "los-angeles", "london"],
  "hiring_velocity_30d": 47,
  "as_of": "2026-05-06"
}

Firm headcount timeline #

Hiring velocity #

Compare firms #

curl -X POST https://api.placement.solutions/v1/firms/compare \
  -H "Authorization: Bearer pk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "ids": ["frm_kirkland", "frm_paul_weiss", "frm_skadden"] }'

requests.post("https://api.placement.solutions/v1/firms/compare",
    headers={
        "Authorization": "Bearer pk_live_REPLACE_ME",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"ids": ["frm_kirkland", "frm_paul_weiss", "frm_skadden"]}).json()

Lateral moves #

Partner departures #

Practice areas #

Markets #

Usage events #

Account info #

{
  "tenant": { "id": "ten_01J9X...", "name": "Acme Legal Newsroom", "tier": "webhook", "data_residency": "us" },
  "key":    { "id": "key_01J9X...", "prefix": "pk_live_", "scopes": ["jobs:read", "firms:read"], "ip_allowlist": ["203.0.113.0/24"] },
  "limits": { "month_quota": null, "month_used": 38421, "minute_limit": null, "burst_limit": 300, "burst_remaining": 287 }
}

Create API key #

Exports #

{
  "data": [
    {
      "id": "exp_01J9X...",
      "kind": "lateral_moves",
      "format": "csv",
      "status": "ready",
      "row_count": 18241,
      "signed_url": "https://exports.placement.solutions/exp_01J9X.../moves.csv?expires=...",
      "expires_at": "2026-05-07T14:22:31Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Reverse-engineer a job description #

curl -X POST https://api.placement.solutions/v1/reverse-engineer \
  -H "Authorization: Bearer pk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "text": "Confidential search for senior associate, complex commercial litigation, MDL experience, NY office of an AmLaw 50 firm with strong life-sciences book.", "target": "firm", "top_k": 5 }'

import requests, uuid
requests.post("https://api.placement.solutions/v1/reverse-engineer",
    headers={
        "Authorization": "Bearer pk_live_REPLACE_ME",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "text": "Confidential search for senior associate, complex commercial litigation...",
        "target": "firm",
        "top_k": 5,
    }).json()

await fetch("https://api.placement.solutions/v1/reverse-engineer", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_live_REPLACE_ME",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ text: "...", target: "firm", top_k: 5 }),
}).then(r => r.json());

{
  "data": [
    {
      "rank": 1,
      "firm_id": "frm_paul_weiss",
      "firm_name": "Paul Weiss",
      "confidence_score": 0.91,
      "confidence_tier": "high",
      "reasoning": [
        { "chip": "Lit-MDL volume in NY", "weight": 0.31 },
        { "chip": "Life-sciences book Q1 2026", "weight": 0.24 },
        { "chip": "AmLaw 50 tier match", "weight": 0.18 },
        { "chip": "Senior-associate hiring velocity", "weight": 0.18 }
      ]
    },
    {
      "rank": 2,
      "firm_id": "frm_paul_hastings",
      "firm_name": "Paul Hastings",
      "confidence_score": 0.78,
      "confidence_tier": "medium",
      "reasoning": [ { "chip": "NY MDL footprint", "weight": 0.27 } ]
    }
  ],
  "request_id": "req_01J9X..."
}

List API keys #

Retrieve an API key #

Update an API key #

Revoke an API key #

List team members #

Invite a team member #

Update a team member #

Remove a team member #

Create an export #

curl -X POST https://api.placement.solutions/v1/exports \
  -H "Authorization: Bearer pk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "kind": "lateral_moves", "filters": {"since": "2026-01-01"}, "format": "csv" }'

import requests, uuid
requests.post("https://api.placement.solutions/v1/exports",
    headers={"Authorization": "Bearer pk_live_REPLACE_ME",
             "Idempotency-Key": str(uuid.uuid4())},
    json={"kind": "lateral_moves",
          "filters": {"since": "2026-01-01"},
          "format": "csv"}).json()

{
  "id": "exp_01J9X...",
  "status": "queued",
  "kind": "lateral_moves",
  "format": "csv",
  "estimated_row_count": 18241,
  "created_at": "2026-05-06T14:22:31Z"
}

Retrieve an export #

{
  "id": "exp_01J9X...",
  "kind": "lateral_moves",
  "format": "csv",
  "status": "ready",
  "row_count": 18241,
  "byte_size": 6914223,
  "signed_url": "https://exports.placement.solutions/exp_01J9X.../moves.csv?expires=...",
  "expires_at": "2026-05-07T14:22:31Z",
  "created_at": "2026-05-06T14:22:31Z",
  "ready_at":   "2026-05-06T14:24:08Z"
}