Resources

Developer API

Use Heritage Passport's partner endpoint for genealogy tree software, iOS genealogy apps, society websites, and newsletters with technical support. It is built for a pre-opt-in family-tree read: process the GEDCOM, return the result, and retain no raw GEDCOM or member identity unless the visitor continues inside Heritage Passport.

Privacy contract

Pre-opt-in checks stay anonymous in Heritage Passport.

The endpoint receives a GEDCOM only for the family-tree screening. Before opt-in, Heritage Passport stores anonymous attribution only: partner, lead token, tree-match category, whether more questions are required, match country, match generation, status, and timestamps. We do not retain the raw GEDCOM, ancestor names, birth dates, birthplaces, email, user ID, identity documents, or payment data.

The handoff URL carries a 15-minute signed, single-use token with non-name answers already supplied. If a visitor chooses to continue inside Heritage Passport, the lead can be attached to their account after opt-in and credited on conversion.

Iframe embed

<iframe
  src="https://heritagepassport.co/embed/eligibility?k={{partner_slug}}"
  width="100%"
  height="640"
  loading="lazy">
</iframe>

Script widget

<div id="hp-eligibility"></div>
<script
  src="https://heritagepassport.co/embed/widget.js"
  data-partner="{{partner_slug}}">
</script>

Endpoint reference

Secret keys are server-side only. Browser embeds use the public slug and call the slug-based embed endpoint.

POST /api/partner/v1/eligibility
Authorization: Bearer hp_partner_...
Content-Type: multipart/form-data

file=<GEDCOM .ged file>

Alternative JSON:
{
  "gedcom_base64": "...",
  "root_person_id": "@I1@"
}

200 OK
{
  "tree_match": "strong" | "potential" | "none" | "indeterminate",
  "additional_questions_required": true,
  "paths": [
    {
      "country_iso": "IE",
      "country_name": "Ireland",
      "route_keys": ["ireland-fbr", "ireland-passport"],
      "tree_match": "potential",
      "additional_questions_required": true,
      "match": {
        "relationship": "Grandfather",
        "ahnentafel": 4,
        "country_of_birth": "Ireland",
        "birth_place_raw": "Galway, Ireland",
        "resolved_iso": "IE",
        "birth_year": 1930
      }
    }
  ],
  "lead_token": "{{opaque_lead_token}}",
  "handoff_url": "https://heritagepassport.co/start?handoff={{signed_single_use_token}}"
}

Rate limits default to 60 requests per minute per active partner key. Error codes use normal HTTP statuses: 400 validation, 401 invalid key, 429 rate limit, 500/503 server failure. `paths` contains one card-ready entry per country with a strong or potential match; it is empty when no path can be shown. These values describe the tree screen, not legal eligibility; the handoff continues into the standard country assessment.

GET /api/partner/v1/report
Authorization: Bearer hp_partner_...

200 OK
{
  "eligibility_calls": 120,
  "leads_captured": 18,
  "handoffs_consumed": 14,
  "conversions": 3,
  "revenue_share_to_date": { "amount": 267, "currency": "usd" }
}

Get a key

Mission-only keys are issued immediately. Rev-share keys start pending so we can review placement and activate the ledger together.

Program overview is on the Partners page.