Skip to content
SeekOutDevelopers

Get started

Quickstart

Verify a key in about five minutes. You will create a live API key, call GET /v1/whoami, run a preview search, and unlock a profile from one of the results.

  1. Create a live API key

    Open API keys and create a key. Grant the Candidate search and Profile unlock access sets so the same key can search and then unlock. Live keys spend your organization's credits on paid calls, so add credits in the console before you unlock a profile.

    Shown once

    The key is displayed a single time. Store it as SEEKOUT_API_KEY in your environment — never in source control. If you lose it, rotate the key and revoke the old one.

  2. Verify the key

    GET /v1/whoami needs no extra permission and does not charge credits. It is the fastest way to confirm the key reaches this API.

    curl --request GET "https://developer-api.seekout.io/v1/whoami" \
  --header "Authorization: Bearer $SEEKOUT_API_KEY"

    A 200 response names the workspace and the exact scopes on the key. It never invents an organization_id. The audience is this deployment's logical API identifier, not a host you call.

    {
  "org_root": "org_…",
  "workspace_id": "ws_…",
  "application_id": "app_…",
  "credential_id": "cred_…",
  "audience": "https://api.seekout.io/prod",
  "credential_class": "workspace_api_key",
  "scopes": ["candidates.search", "profiles.v1:unlock", "person_matches.execute"]
}

  3. Search candidates

    POST /v1/candidates/search with include: preview returns ranked people and does not spend credits. This sample uses a current-title filter on the public index. Copy results[0].person_id from the response — that is the identifier Unlock accepts.

    curl --request POST "https://developer-api.seekout.io/v1/candidates/search" \
  --header "Authorization: Bearer $SEEKOUT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "searches": [
      {
        "source": "public",
        "query": {
          "current_titles": ["Software Engineer"],
          "regions": ["north_america"]
        }
      }
    ],
    "include": "preview"
  }'

    A 200 response looks like this. Live results use a different person_id for your organization; never invent one.

    {
  "schema_version": "candidate_search_response.v1",
  "search_id": "sset_example",
  "include": "preview",
  "results": [
    {
      "rank": 1,
      "person_id": "person_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "search_result_ref": "sr_example",
      "sources": ["public"],
      "matched_sources": ["public"],
      "summary": {
        "full_name": "Example candidate",
        "current_title": "Software Engineer"
      }
    }
  ],
  "pagination": { "cursor": "cur_example", "has_more": true },
  "billing": { "charge_units": 0, "include": "preview" }
}

    Try it from Candidate search. Paste the same key, send, then open Unlock — Try it fills person_id from the first result.

  4. Retrieve a contact

    POST /v1/contacts retrieves an email address, a phone number, or both for the same person_id. Each channel succeeds or fails on its own, and only a delivered channel spends credits.

    curl --request POST "https://developer-api.seekout.io/v1/contacts" \
  --header "Authorization: Bearer $SEEKOUT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "person_id": "person_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "channels": ["email", "phone"]
  }'

    A 200 carries the values. If the provider outlasts the request budget you get 202 with a job id instead — read it back, or register a webhook. See contacts, contact jobs, and webhooks.

  5. Unlock a profile

    POST /v1/profiles/unlock opens the full record for one opaque person_id from Search. The Idempotency-Key header makes the request safe to retry: the same key replays the same logical unlock instead of charging again.

    curl --request POST "https://developer-api.seekout.io/v1/profiles/unlock" \
  --header "Authorization: Bearer $SEEKOUT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "person_id": "person_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }'

    Replace the sample person_id with the one Search just returned. The reply carries person_id, operation_id, outcome, charged microunits, and the profile. Try it from Unlock profiles.

Next steps