Partner cohort API

SourceHire exposes a small read-only HTTP API that surfaces aggregate cohort statistics to a named data partner (currently: LiveRamp). The API is consent-gated, audit-logged, rate-limited, and returns no individual candidate records. This page is the public, candidate-readable specification of exactly what that API does and does not do.

Consent gate

On every request, the API resolves the set of contributing candidates by running the following four-step filter, in order:

1. Not soft-deleted (Candidate.deletedAt is null).
2. Has no pending deletion request (DeletionRequest with fulfilledAt = null).
3. Has NOT set doNotSellOrShareAt — honors CCPA opt-out, the “Do Not Sell or Share My Personal Information” form, and the Global Privacy Control browser signal.
4. Latest consent ledger entry for data_partner_smmt_audience_share is set to granted. Revoked candidates fall out of the audience immediately on the next request, no cache, no delay.

Suppression policy

Any cohort with fewer than 5 contributing candidates is omitted from the response. We do not return the cohort label with a suppressed count — the label itself can be identifying for tiny cohorts. The minimum is enforced inside the SQL query, not at the response layer, so no internal client can ever read it pre-suppression.

Each endpoint also caps at 50 cohorts per response, ordered by descending count.

Authentication

Every request must include an Authorization: Bearer <token> header with the partner's shared secret. The platform comparison uses a timing-safe equality check. The shared secret is provisioned by SourceHire out of band — never emailed, never committed to source control.

Tokens can be revoked at any time by unsetting the platform environment variable. Revocation takes effect on the next cold start (seconds).

Rate limiting

10 requests per minute per partner key, sliding window. When exceeded the API returns 429 with a Retry-After header indicating seconds to wait.

Audit posture

Every served request writes an AuditLog row tagged partner_api.<endpoint> with timestamp, partner id, IP, user agent, outcome, and latency. Failed-auth and rate-limited requests are not audited (they aren't data accesses); served requests always are. The log is retained for the same period as the platform's general audit log.

Endpoints

{
  "ok": true,
  "as_of": "2026-05-16T14:32:00.000Z",
  "consented_audience_total": 1247,
  "can_query_cohorts": true,
  "api_version": "v1"
}

{
  "as_of": "2026-05-16T14:32:00.000Z",
  "consented_audience_total": 1247,
  "cohorts": [
    { "label": "salesforce", "count": 234 },
    { "label": "github", "count": 198 },
    { "label": "figma", "count": 142 }
    // ...up to 50 entries
  ]
}

{
  "as_of": "2026-05-16T14:32:00.000Z",
  "consented_audience_total": 1247,
  "cohorts": [
    { "label": "python", "count": 312 },
    { "label": "typescript", "count": 287 }
  ]
}

{
  "as_of": "2026-05-16T14:32:00.000Z",
  "consented_audience_total": 1247,
  "cohorts": [
    { "label": "san francisco, ca", "count": 142 },
    { "label": "new york, ny", "count": 119 }
  ]
}

What the API does NOT do

• It does not return any individual candidate record.
• It does not return any cohort smaller than five candidates, even if you ask for one explicitly. The suppression is at the SQL layer, not the response layer.
• It does not return data about candidates who haven't granted the explicit LiveRamp consent. Implicit consent, inferred consent, and recruiter-attested consent flagged recruiter_attested:* do not count as candidate consent for this surface, regardless of policy version.
• It does not return data about candidates with a CCPA opt-out, GPC signal, or pending deletion request.
• It does not breakdown cohorts by protected-class attribute (race, gender, age, religion, disability). Those fields are not in the SourceHire schema; they cannot appear in the response.
• It does not accept POST, PUT, or DELETE.

Revoking your inclusion

You can revoke the “Share with LiveRamp” consent at any time from /apply/me or /privacy-choices. Your revocation takes effect on the next partner API request — you fall out of the audience immediately, with no propagation delay. Any cohort counts LiveRamp previously pulled will still reflect your old inclusion (we can't un-pull a response from the past), but no future response will include you.

You may also exercise the full data-export and right-to-erasure rights described in our data access portal. If you delete your account, you are removed from this API permanently along with everything else.

Questions or concerns? Email privacy@sourcehire.app. This documentation is versioned alongside the source code; if anything here disagrees with what the API actually does, the code is the spec — please report the discrepancy.