{"info":{"_postman_id":"451c77b4-ee7d-483c-9ccf-58698b02a70b","name":"Hatch Partner API","description":"

Hatch Partner API Documentation (Postman)

Overview

The Hatch Partner API turns sparse person records into Complete Human Profiles suitable for CRMs, fundraising, and marketing automation. Results include identity, contact, education, career, wealth signals, social presence, and an AI-generated bio, returned as a normalized JSON object you can store field-by-field or as a whole profile.

API Demo

Interactive API documentation available at: https://hatch-parter-api.readme.io/reference/submitprospects

Core Flow (Asynchronous)

Submit one or more prospects to the Partner API with all the identifiers you have.
\n
Enrichment runs asynchronously; when finished we POST to your callback_url.
\n
You can poll results anytime via the results_url returned on submit - this returns an array of profile URLs.
\n
Fetch each profile by calling the URLs returned in the results array to get the full enriched data.
\n

This pattern supports large jobs, retries, and resilient processing.

Authentication

All endpoints require an API key to be supplied in a header:

Endpoint: POST https://etl.hatch.ai/api/partner_api
\n
Header key: partnerapi
\n
Header value: YOUR_API_KEY
\n

Minimum Required Fields (per prospect)

Required (enforced): UserID, org_id, org_name, FirstName, LastName
\n
Plus at least one of: email, phone, or address (city + state minimum)
\n

\n
Note: Providing more identifiers generally increases match rate and accuracy.
\n

Enrichment Flags (Partner API)

Partner API clients can selectively enable/disable enrichment operations by passing an enrichment_flags object in the upload payload. All flags default to true (enabled) when omitted, preserving backward compatibility.

Usage

{\n  \"organization\": {\"OrganizationName\": \"Partner Name\"},\n  \"enrichment_flags\": {\n    \"profile_picture\": true,\n    \"home_value\": true,\n    \"affluence_score\": true,\n    \"ai_summary\": true\n  },\n  \"prospects\": [...]\n}\n\n

What's in a Profile (Typical Fields)

Scores: match_confidence (0–100), social_influence, affluence_score
\n
Identity and Summary: profile photo, AI-generated bio (headline/summary/extended), name components, date or year of birth, interests
\n
Contact: emails, phones, current and prior postal addresses (may include home details and links when available)
\n
Education: institutions, degrees, dates
\n
Career: current and past roles; employer metadata (industry, size, website); work email where available
\n
Social Graph: links/handles and light reach metrics for LinkedIn, X/Twitter, Facebook; optionally Instagram, YouTube, GitHub, TikTok, Pinterest, Reddit
\n

Match Types, Info Accuracy, and the Scorecard

Each result includes a Match Type (e.g., LinkedInMatch.FullNameMatch, EmailMatch.FullNameMatch, PhoneMatch.FullNameMatch, FullNameMatch.AddressHashMatch). Each Match Type maps to a baseline Info Accuracy score (0–100). Only the highest-precedence match type is shown.

The Scorecard compares your submitted data to the matched profile, exposing booleans and graded comparisons such as:

email_match, phone_match, address_match, CSZ_match (city/state/ZIP), state_only_match, zip_match
\n
first_name_match (exact, similar, nickname, or no match)
\n
last_name_match (exact, similar, or no match)
\n
middle_name_or_init_match (true, false, or not provided)
\n

The Scorecard also includes match_type and total_final_score (0–100). Use these fields to gate merges, auto-attach rules, and downstream automation with confidence.

Match Types Reference

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Match Type	Info Accuracy Score
LinkedInMatch.FullNameMatch	100
LinkedInMatch.FirstNameMatch.HashOrPhoneMatch.Yes	95
LinkedInMatch.FirstNameMatch.HashOrPhoneMatch.No	85
LinkedInMatch.LastNameMatch.HashOrPhoneMatch.Yes	94
LinkedInMatch.LastNameMatch.HashOrPhoneMatch.No	84
LinkedInMatch.NoNameMatch.HashOrPhoneMatch.Yes	93
LinkedInMatch.NoNameMatch.HashOrPhoneMatch.No	61
EmailMatch.FullNameMatch	99
EmailMatch.FirstNameMatch.HashOrPhoneMatch.Yes	94
EmailMatch.FirstNameMatch.HashOrPhoneMatch.No	84
EmailMatch.LastNameMatch.HashOrPhoneMatch.Yes.MiddleNameOrInitialMatch.Yes	90
EmailMatch.LastNameMatch.HashOrPhoneMatch.Yes.MiddleNameOrInitialMatch.No	75
EmailMatch.LastNameMatch.HashOrPhoneMatch.No.MiddleNameOrInitialMismatchOrNoMatch.Yes	74
EmailMatch.LastNameMatch.HashOrPhoneMatch.No.MiddleNameOrInitialMismatchOrNoMatch.No	64
EmailMatch.NoNameMatch.HashOrPhoneMatch.Yes	61
EmailMatch.NoNameMatch.HashOrPhoneMatch.No	51
PhoneMatch.FullNameMatch	98
PhoneMatch.FirstNameMatch	73
PhoneMatch.LastNameMatch	50
PhoneMatch.NoNameMatch	41
FullNameMatch.AddressHashMatch	97
FullNameMatch.CityPlusStateOrZipMatch.OneProfile	75
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialMatch.Multiple	61
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialMatch.One	85
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialNoMatch.Multiple	52
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialNoMatch.One	62
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialMismatch.Multiple	50
FullNameMatch.CityPlusStateOrZipMatch.MultipleProfiles.MiddleNameOrInitialMismatch.One	52
FullNameMatch.StateOnlyMatch.OneProfile	74
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialMatch.Multiple	51
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialMatch.One	50
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialNoMatch.Multiple	50
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialNoMatch.One	41
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialMismatch.Multiple	41
FullNameMatch.StateOnlyMatch.MultipleProfiles.MiddleNameOrInitialMismatch.One	42
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialMatch.Multiple	51
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialMatch.One	50
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialNoMatch.Multiple	41
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialNoMatch.One	50
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialMismatch.Multiple	41
FullNameMatch.HashCityOrStateNoMatch.MiddleNameOrInitialMismatch.One	42
AddressHashMatch.FullNameMatch	96
AddressHashMatch.FirstNameMatch.Address1Match	62
AddressHashMatch.FirstNameMatch.Address1NoMatch	61
AddressHashMatch.LastNameMatch.Address1Match	50
AddressHashMatch.LastNameMatch.Address1NoMatch	49
AddressHashMatch.NoNameMatch	48

Scorecard Field Details

Possible values for first_name_match****:

exact
\n
similar (can be either soundex or typo)
\n
nickname
\n
no match
\n

Possible values for last_name_match****:

exact
\n
similar (can be either soundex or typo)
\n
no match
\n

Possible values for middle_name_or_init_match****:

true
\n
false
\n
not provided
\n

Pragmatic Scoring Tips

Many teams present 0–100 Info Accuracy as 1–5 stars. A common mapping is:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Score Range	Stars
51–60	1 star
61–70	2 stars
71–80	3 stars
81–90	4 stars
91–100	5 stars

\n
Note: Matches below 51 are often suppressed from end-user UIs.
\n

Score Definitions

Information Accuracy Score: A Hatch proprietary (0-5 star or 0-100) rating of the likelihood that the matched profile data represents the correct individual.
\n
Affluence Score: A Hatch proprietary 0-100 score representing the wealth of the prospect, where 100 is the world's richest person, and 0 is someone with no recorded assets or income.
\n
Social Influence Score: A Hatch proprietary 0-100 score that quantifies the strength of an individual's presence, audience, and reach on social media platforms.
\n

Operational Limits (Design Around These)

Annual usage: number of enrichments will be stipulated in your contract
\n
Rate limit (all APIs): max 25 requests / second
\n
Bulk request size: up to 100,000 prospects per bulk request
\n
Processing throughput: average of ~10,000 results/hour across ongoing bulk jobs (each applicable result may include photo, AI summary, social, career, contact, wealth, and scores)
\n

IDs & Variables Used in This Collection

results_id is parsed from results_url returned by Submit Prospects
\n
prospect_url is extracted from the results array returned by Get Results
\n
hatch_id is extracted from prospect_url or from the profile data
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Hatch Partner API Documentation (Postman)","slug":"hatch-partner-api-documentation-postman"}],"owner":"22789297","collectionId":"451c77b4-ee7d-483c-9ccf-58698b02a70b","publishedId":"2sB3dWsnKm","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-12-22T14:58:31.000Z"},"item":[{"name":"Submit Prospects","event":[{"listen":"test","script":{"type":"text/javascript","exec":["// Extract results_id from the submit response (results_url) and store it as a collection variable.","try {"," const json = pm.response.json();"," const resultsUrl = json && json.results_url;"," if (resultsUrl) {"," const m = String(resultsUrl).match(/\\/partner_api_results\\/(\\d+)/);"," if (m && m[1]) {"," pm.collectionVariables.set('results_id', m[1]);"," }"," }","} catch (e) {"," // ignore","}"],"id":"ff0bd8aa-f5ee-4e4b-aea4-6d1a92991ff3"}}],"id":"cea355fa-739c-46e7-8132-12c62a3b0d4f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"

Your Hatch Partner API key.

\n","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"prospects\": [\n {\n \"org_id\": 626,\n \"org_name\": \"Save the Children\",\n \"UserID\": \"81876\",\n \"Gender\": \"Male\",\n \"Prefix\": \"Dr\",\n \"FirstName\": \"Michael\",\n \"MiddleName\": \"J\",\n \"LastName\": \"Smith\",\n \"Suffix\": \"Sr\",\n \"Nickname\": \"Mike\",\n \"Spouse\": \"Maria\",\n \"Keywords\": [\n \"keyword\",\n \"multi word keyword\"\n ],\n \"Email\": \"msmith@gmail.com\",\n \"PersonalEmail\": null,\n \"WorkEmail\": null,\n \"OtherEmail\": null,\n \"BulkEmails\": [\n \"msmith@outlook.com\",\n \"msmith@aol.com\"\n ],\n \"Phone\": \"(516) 924-2664\",\n \"HomePhone\": null,\n \"FamilyPhone\": null,\n \"MobilePhone\": null,\n \"BusinessPhone\": null,\n \"OtherPhone\": null,\n \"BulkPhones\": [\n \"+19143456789\",\n \"(914) 453-1234\"\n ],\n \"Address\": \"12 Willow Lane\",\n \"Address2\": \"Apt A\",\n \"City\": \"Great Neck\",\n \"State\": \"NY\",\n \"Postalcode\": \"11023\",\n \"Country\": \"United States\",\n \"JobTitle\": null,\n \"Company\": null,\n \"Birthday\": null,\n \"Linkedin\": null,\n \"Facebook\": null,\n \"Twitter\": null,\n \"Instagram\": null\n }\n ],\n \"callback_url\": \"https://partner.com/enrichment_callback\"\n}"},"url":"https://etl.hatch.ai/api/partner_api","description":"

Submit Prospects

Submit one or more prospects for asynchronous enrichment.

Endpoint

POST https://etl.hatch.ai/api/partner_api

Auth

partnerapi: YOUR_API_KEY

Request Body Structure

The API expects a JSON object as the request body with these root keys:

prospects (array): prospect objects
\n
callback_url (string): HTTPS endpoint to receive completion notifications
\n

Minimum Required Fields per Prospect

Required (enforced):

UserID, org_id, org_name, FirstName, LastName

Plus at least one of:

Email or Phone or address (ideally all address fields; city + state minimum)

\n
Providing more data points will result in higher match rate and accuracy, and better enrichment results.
\n

Request Parameters Description

prospects (array of objects)

A list of prospect records. Each object in the array may contain the following fields:

Field	Type	Required	Description
`org_id`	integer	Yes	The unique id (from the partner platform) for the organization that owns the prospect that is being enriched.
`org_name`	string	Yes	The name (from the partner platform) of the organization that owns the prospect that is being enriched.
`UserID`	string	Yes	The unique id (from the partner platform) for the prospect that is being enriched.
`Gender`	string	No	The gender of the prospect (e.g., Male, Female, Unknown). Nullable.
`Prefix`	string	No	The prefix of the prospect's name. Nullable.
`FirstName`	string	Yes	The first name of the prospect.
`MiddleName`	string	No	Middle name of the prospect. Nullable.
`LastName`	string	Yes	The last name of the prospect.
`Suffix`	string	No	The suffix of the prospect's name. Nullable.
`Nickname`	string	No	Nickname of the prospect. Nullable.
`Spouse`	string	No	Spouse name. Nullable.
`Keywords`	array of strings	No	Keywords associated with the prospect.
`Email`	string	Conditional	The primary email of the prospect. (At least one of Email, Phone, or Address required)
`PersonalEmail`	string	No	Personal email of the prospect. Nullable.
`WorkEmail`	string	No	Work email of the prospect. Nullable.
`OtherEmail`	string	No	Other email of the prospect. Nullable.
`BulkEmails`	array of strings	No	A list of emails of the prospect.
`Phone`	string	Conditional	The primary phone number of the prospect. (At least one of Email, Phone, or Address required)
`HomePhone`	string	No	Home phone number. Nullable.
`FamilyPhone`	string	No	Family phone number. Nullable.
`MobilePhone`	string	No	Mobile phone number. Nullable.
`BusinessPhone`	string	No	Business phone number. Nullable.
`OtherPhone`	string	No	Other phone number of the prospect. Nullable.
`BulkPhones`	array of strings	No	A list of phone numbers of the prospect.
`Address`	string	Conditional	The first line of the primary address of the prospect. (At least one of Email, Phone, or Address required)
`Address2`	string	No	The second line of the primary address of the prospect. Nullable.
`City`	string	Conditional	The city of the primary address of the prospect. (Required if using address)
`State`	string	Conditional	The state of the primary address of the prospect. (Required if using address)
`Postalcode`	string	No	The postal code of the primary address of the prospect.
`Country`	string	No	The country of the primary address of the prospect.
`Birthday`	string	No	The birthday of the prospect in ISO 8601 format. Nullable.
`JobTitle`	string	No	Job title of the prospect. Nullable.
`Company`	string	No	The company name associated with the prospect. Nullable.
`Linkedin`	string	No	LinkedIn profile link. Nullable.
`Facebook`	string	No	Facebook profile link. Nullable.
`Twitter`	string	No	Twitter profile link. Nullable.
`Instagram`	string	No	Instagram profile link. Nullable.

callback_url (string)

Specifies the URL to which the API sends a notification once enrichment is complete.

Response

Success Response:

Code: 200 OK
\n
Content: A JSON object indicating the success of the operation
\n

On success, returns status: \"success\" and a results_url you can poll.

Error Response:

Code: 4XX/5XX
\n
Content: A JSON object with an error message explaining the issue.
\n

\n
Tip: Results can be accessed in real time at any moment when the partner wishes. A notification indicating the enrichment process finished will be sent to the callback URL once the enriched data for all prospects is available.
\n

\n
Tip: this collection extracts results_id from results_url automatically in the Tests tab.
\n

\n","urlObject":{"path":["api","partner_api"],"host":["https://etl.hatch.ai"],"query":[],"variable":[]}},"response":[{"id":"1bff60cb-e69a-4893-9e99-e7c606ff9e5c","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"Your Hatch Partner API key.","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"prospects\": [\n {\n \"org_id\": 626,\n \"org_name\": \"Save the Children\",\n \"UserID\": \"81876\",\n \"Gender\": \"Male\",\n \"Prefix\": \"Dr\",\n \"FirstName\": \"Michael\",\n \"MiddleName\": \"J\",\n \"LastName\": \"Smith\",\n \"Suffix\": \"Sr\",\n \"Nickname\": \"Mike\",\n \"Spouse\": \"Maria\",\n \"Keywords\": [\n \"keyword\",\n \"multi word keyword\"\n ],\n \"Email\": \"msmith@gmail.com\",\n \"PersonalEmail\": null,\n \"WorkEmail\": null,\n \"OtherEmail\": null,\n \"BulkEmails\": [\n \"msmith@outlook.com\",\n \"msmith@aol.com\"\n ],\n \"Phone\": \"(516) 924-2664\",\n \"HomePhone\": null,\n \"FamilyPhone\": null,\n \"MobilePhone\": null,\n \"BusinessPhone\": null,\n \"OtherPhone\": null,\n \"BulkPhones\": [\n \"+19143456789\",\n \"(914) 453-1234\"\n ],\n \"Address\": \"12 Willow Lane\",\n \"Address2\": \"Apt A\",\n \"City\": \"Great Neck\",\n \"State\": \"NY\",\n \"Postalcode\": \"11023\",\n \"Country\": \"United States\",\n \"JobTitle\": null,\n \"Company\": null,\n \"Birthday\": null,\n \"Linkedin\": null,\n \"Facebook\": null,\n \"Twitter\": null,\n \"Instagram\": null\n }\n ],\n \"callback_url\": \"https://partner.com/enrichment_callback\"\n}"},"url":"https://etl.hatch.ai/api/partner_api"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"results_url\": \"https://etl.hatch.ai/api/partner_api_results/180430166005\",\n \"status\": \"success\"\n}"}],"_postman_id":"cea355fa-739c-46e7-8132-12c62a3b0d4f"},{"name":"Get Results (poll by results_id)","event":[{"listen":"test","script":{"type":"text/javascript","exec":["// Extract the first prospect_url from the results array and store it as a collection variable.","try {"," const json = pm.response.json();"," if (json && json.results && json.results.length > 0) {"," const firstUrl = json.results[0];"," pm.collectionVariables.set('prospect_url', firstUrl);"," // Also extract hatch_id from the URL"," const m = String(firstUrl).match(/\\/prospect\\/(\\d+)/);"," if (m && m[1]) {"," pm.collectionVariables.set('hatch_id', m[1]);"," }"," }","} catch (e) {"," // ignore","}"],"id":"2d4ba928-3976-4a40-a5b9-6f4b197215e1"}}],"id":"967524f7-310d-4fdc-a100-eb6c9fb57548","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"

Your Hatch Partner API key.

\n","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"https://etl.hatch.ai/api/partner_api_results/180430166005","description":"

Get Results (Poll by results_id)

Poll the enrichment job output using the results_url returned by Submit Prospects.

Endpoint

GET https://etl.hatch.ai/api/partner_api_results/180430166005

Auth

partnerapi: YOUR_API_KEY

What you get back

Returns an object containing an array of profile URLs - one URL for each enriched prospect. The array may grow as processing completes.

{\n  \"results\": [\n    \"https://partner.hatch.ai/api/partner/prospect/265981889265\",\n    \"https://partner.hatch.ai/api/partner/prospect/466630366882\"\n  ]\n}\n

Each URL in the results array can be called directly to retrieve the full enriched profile data.

Next Step

Call each URL from the results array using Get Prospect Details to retrieve the full profile data.

\n
Tip: this collection extracts the first prospect_url and hatch_id automatically from the response in the Tests tab.
\n

\n","urlObject":{"path":["api","partner_api_results","180430166005"],"host":["https://etl.hatch.ai"],"query":[],"variable":[]}},"response":[{"id":"44a3900f-a1e1-4a30-9043-c0933f13ce9d","name":"200 Success - Array of Profile URLs","originalRequest":{"method":"GET","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"Your Hatch Partner API key.","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"https://etl.hatch.ai/api/partner_api_results/180430166005"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"results\": [\n \"https://partner.hatch.ai/api/partner/prospect/265981889265\"\n ]\n}"}],"_postman_id":"967524f7-310d-4fdc-a100-eb6c9fb57548"},{"name":"Get Prospect Details","id":"7380d11d-f225-4e98-8896-8ecea9557ea3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"

Your Hatch Partner API key.

\n","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"https://partner.hatch.ai/api/partner/prospect/265981889265","description":"

Get Prospect Details (Full Profile Fetch)

Fetch the full enriched profile for a single individual using the URL returned by Get Results.

Endpoint

Use the URL directly from the results array, e.g.:
GET https://partner.hatch.ai/api/partner/prospect/265981889265

Or use the https://partner.hatch.ai/api/partner/prospect/265981889265 variable populated by the previous request.

Auth

partnerapi: YOUR_API_KEY

When to use

After polling Get Results and receiving profile URLs
\n
To fetch the full enriched data for each prospect
\n

What you get back

Returns the full enriched profile object with all available data:

Scores

hatch_id - Unique Hatch identifier
\n
match_type - The matching method used (see Match Types Reference in collection description)
\n
match_confidence (0-100) - Confidence score for the match
\n
affluence_score - Wealth indicator (0-100, where 100 is the world's richest person)
\n
social_influence - Social media presence score (0-100)
\n

Scorecard

Comparison results between submitted data and matched profile:

email_match, phone_match, address_match (boolean)
\n
address_hash_match, CSZ_match, city_state_match (boolean)
\n
state_match, state_only_match, zip_match (boolean)
\n
first_name_match (\"exact\", \"similar\", \"nickname\", or \"no match\")
\n
last_name_match (\"exact\", \"similar\", or \"no match\")
\n
middle_name_or_init_match (\"true\", \"false\", or \"not provided\")
\n
total_final_score (0-100)
\n

Identity & Summary

Name components: first_name, last_name, middle_name, nickname, prefix, suffix
\n
gender (data: 1=Male, 2=Female)
\n
date_of_birth with day/month/year objects and estimated flags
\n
profile_photo - LinkedIn profile photo URL
\n
ai_summary containing:
\n
- ai_bio_headline - Short professional headline
  \n
- ai_bio_summary - Brief bio paragraph
  \n
- ai_bio_extended - Full detailed biography
  \n
\n
interests - Array of interest objects
\n
skills - Array of skill objects
\n

Contact

emails - Array with data and is_primary fields
\n
phones - Array with data and is_primary fields
\n
addresses - Array with full address details including:
\n
- address, city, state, zip, full_address
  \n
- street_address, street_address2
  \n
- is_primary
  \n
- zillow property data (when available): bedrooms, bathrooms, square_feet_size, price, zestimate, rent_estimate, year_build, home_type, county, latitude/longitude
  \n
\n

Education

education - Array with:
- school_name, school_id
  \n
- degree
  \n
- start_date, end_date
  \n
\n

Career

career - Array with:
- organization, organization_id
  \n
- title, role, levels
  \n
- industry, size, type
  \n
- start_date, end_date, is_current
  \n
- work_email, work_phones
  \n
- address, website
  \n
- ticker (stock exchange info)
  \n
- summary
  \n
\n

\n\n

social_media object containing profiles for:
\n
- linkedin - Handle, URL, followers, profile photo
  \n
- facebook - Handle, URL, followers
  \n
- twitter - Handle, URL, followers
  \n
- instagram - Handle, URL
  \n
- github - Handle, URL
  \n
- youtube - Handle, URL
  \n
- tiktok - Handle, URL
  \n
- pinterest - Handle, URL
  \n
- reddit - Handle, URL
  \n
- websites - Array of website URLs
  \n
- social_influence_score - Aggregate social presence score
  \n
\n

\n","urlObject":{"host":["https://partner.hatch.ai/api/partner/prospect/265981889265"],"query":[],"variable":[]}},"response":[{"id":"cd9841bf-70a1-446b-a9ee-f40c48cd1c45","name":"200 Complete Profile Example","originalRequest":{"method":"GET","header":[{"key":"partnerapi","value":"YOUR_API_KEY","description":"Your Hatch Partner API key.","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"https://partner.hatch.ai/api/partner/prospect/466630366882"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"addresses\": [\n {\n \"address\": \"1035 le green street\",\n \"city\": \"houston\",\n \"full_address\": \"1035 le green street, houston, texas, 77009\",\n \"is_primary\": true,\n \"state\": \"texas\",\n \"street_address\": \"1035 le green street\",\n \"street_address2\": null,\n \"zillow\": {\n \"annual_home_owners_insurance\": null,\n \"bathrooms\": 1,\n \"bedrooms\": 2,\n \"county\": \"Harris County\",\n \"description\": \"This 480 square foot single family home has 2 bedrooms and 1.0 bathrooms.\",\n \"home_type\": \"SINGLE_FAMILY\",\n \"last_sold_price\": null,\n \"latitude\": 29.798664,\n \"listing_area_value\": 480,\n \"longitude\": -95.38584,\n \"price\": 510400,\n \"rent_estimate\": 1242,\n \"square_feet_size\": 480,\n \"year_build\": 1930,\n \"zestimate\": 510400,\n \"zpid\": 27853518\n },\n \"zip\": \"77009\"\n }\n ],\n \"afluence_score\": {\n \"afluence_score\": 33.0\n },\n \"ai_summary\": {\n \"ai_bio_extended\": \"Kathleen Name, born in June 1949, is a distinguished figure in higher education, currently serving as the Executive Director of Academic Programs and Advising at the University of Houston since 2009.\",\n \"ai_bio_headline\": \"Executive Director | Higher Education Advocate | Philanthropist | Lifelong Learner\",\n \"ai_bio_summary\": \"Kathleen Name is the Executive Director of Academic Programs and Advising at the University of Houston.\"\n },\n \"career\": [\n {\n \"address\": \"4800 calhoun road, houston, texas, 77004, united states\",\n \"end_date\": null,\n \"industry\": \"higher education\",\n \"is_current\": true,\n \"levels\": [\"director\"],\n \"organization\": \"university of houston\",\n \"organization_id\": null,\n \"role\": null,\n \"size\": \"10001+\",\n \"start_date\": {\n \"__type\": \"Date\",\n \"iso\": \"2009-09-01T00:00:00.000Z\"\n },\n \"summary\": null,\n \"ticker\": {\n \"stock_exchange\": \"university of houston\",\n \"ticker\": null\n },\n \"title\": \"executive director, academic programs and advising\",\n \"type\": \"private\",\n \"website\": \"uh.edu\",\n \"work_email\": \"williamson@uhcl.edu\",\n \"work_phones\": []\n }\n ],\n \"date_of_birth\": {\n \"date\": {\n \"day\": {\"data\": 8, \"estimated\": false},\n \"month\": {\"data\": 6, \"estimated\": false},\n \"year\": {\"data\": 1949, \"estimated\": false}\n },\n \"place\": {\"data\": null}\n },\n \"education\": [\n {\n \"degree\": \"doctorates/doctor of philosophy\",\n \"end_date\": \"1995\",\n \"school_id\": \"AZH7quZhtYg1ZqOCKbQxBw_0\",\n \"school_name\": \"uh hrd\",\n \"start_date\": \"1989\"\n },\n {\n \"degree\": \"master of business administration/masters\",\n \"end_date\": \"1987\",\n \"school_id\": \"AZH7quZhtYg1ZqOCKbQxBw_0\",\n \"school_name\": \"uh hrd\",\n \"start_date\": \"1983\"\n },\n {\n \"degree\": \"bachelors/bachelor of arts\",\n \"end_date\": \"1972\",\n \"school_id\": \"BbHT7ckKwgq7lvLQEOol8Q_0\",\n \"school_name\": \"rice university\",\n \"start_date\": \"1967\"\n }\n ],\n \"emails\": [\n {\"data\": \"kdvl@aol.com\", \"is_primary\": true},\n {\"data\": \"williamson@uhcl.edu\", \"is_primary\": true}\n ],\n \"first_name\": \"kathleen\",\n \"gender\": {\"data\": 2},\n \"hatch_id\": \"466630366882\",\n \"interests\": [\n {\"data\": \"marketing\"},\n {\"data\": \"hiking\"}\n ],\n \"last_name\": \"name\",\n \"match_confidence\": \"84\",\n \"match_type\": \"EmailMatch.FirstNameMatch.HashOrPhoneMatch.No\",\n \"middle_name\": {\"data\": \"Michael\"},\n \"nickname\": {\"data\": \"mike\"},\n \"phones\": [\n {\"data\": \"+1(713) 203-4551\", \"is_primary\": true},\n {\"data\": \"+1(713) 861-1397\", \"is_primary\": false},\n {\"data\": \"+1(713) 861-8314\", \"is_primary\": false}\n ],\n \"prefix\": null,\n \"profile_photo\": {\n \"data\": \"https://media.licdn.com/dms/image/profile-photo.jpg\"\n },\n \"Scorecard\": {\n \"CSZ_match\": true,\n \"address_hash_match\": true,\n \"address_match\": true,\n \"city_state_match\": true,\n \"email_match\": true,\n \"first_name_match\": \"nickname\",\n \"last_name_match\": \"exact\",\n \"match_type\": \"EmailMatch.FullNameMatch\",\n \"middle_name_or_init_match\": \"not provided\",\n \"phone_match\": false,\n \"state_match\": true,\n \"state_only_match\": false,\n \"total_final_score\": \"99\",\n \"zip_match\": true\n },\n \"skills\": [\n {\"data\": \"marketing communications\"},\n {\"data\": \"higher education\"}\n ],\n \"social_influence\": {\"data\": 22},\n \"social_media\": {\n \"facebook\": {\n \"handle\": {\"data\": \"kathleen.williamson.393\"},\n \"info\": {\n \"followers\": null,\n \"profile_photo_path\": null,\n \"url\": \"https://www.facebook.com/kathleen.williamson.393\"\n }\n },\n \"github\": {\n \"handle\": {\"data\": \"smartdev89439834\"},\n \"info\": {\n \"followers\": null,\n \"profile_photo_path\": null,\n \"url\": \"https://www.github.com/smartdev89439834\"\n }\n },\n \"instagram\": {\n \"handle\": {\"data\": \"ighandle049804354\"},\n \"info\": {\n \"followers\": null,\n \"url\": \"https://www.instagram.com/ighandle049804354\"\n }\n },\n \"linkedin\": {\n \"handle\": {\"data\": \"kathleen-williamson-861a338\"},\n \"info\": {\n \"followers\": 216,\n \"profile_photo_path\": \"https://media.licdn.com/profile-photo.jpg\",\n \"url\": \"https://www.linkedin.com/in/kathleen-williamson-861a338\"\n }\n },\n \"pintrest\": {\n \"handle\": {\"data\": \"pinteresthandle4353425345\"},\n \"info\": {\n \"followers\": 216,\n \"url\": \"https://www.pinterest.com/pinteresthandle4353425345\"\n }\n },\n \"reddit\": {\n \"handle\": {\"data\": \"reddithandle983489344\"},\n \"info\": {\n \"followers\": 216,\n \"url\": \"https://www.reddit.com/reddithandle983489344\"\n }\n },\n \"social_influence_score\": {\"data\": 22},\n \"tiktok\": {\n \"handle\": {\"data\": \"tiktokhandle3448934\"},\n \"info\": {\n \"followers\": 216,\n \"url\": \"https://www.tiktok.com/tiktokhandle3448934\"\n }\n },\n \"twitter\": {\n \"handle\": {\"data\": \"twitterhandle233\"},\n \"info\": {\n \"followers\": 216,\n \"url\": \"https://www.twitter.com/twitterhandle233\"\n }\n },\n \"websites\": [{\"url\": \"uh.edu\"}],\n \"youtube\": {\n \"handle\": {\"data\": \"ythandle\"},\n \"info\": {\n \"followers\": 216,\n \"url\": \"https://www.youtube.com/ythandle\"\n }\n }\n },\n \"suffix\": \"Mr.\",\n \"user_id\": \"19417086\"\n}"}],"_postman_id":"7380d11d-f225-4e98-8896-8ecea9557ea3"}],"variable":[{"key":"base_url","value":"https://etl.hatch.ai","type":"string","description":"Base URL for the Hatch Partner API (production)."},{"key":"api_key","value":"YOUR_API_KEY","type":"string","description":"Your Hatch Partner API key, sent as the partnerapi request header."},{"key":"results_id","value":"180430166005","type":"string","description":"Results job ID parsed from `results_url` (Submit Prospects response). Used to poll `partner_api_results`."},{"key":"prospect_url","value":"https://partner.hatch.ai/api/partner/prospect/265981889265","type":"string","description":"Full URL to a specific prospect profile, extracted from the results array. Used by Get Prospect Details."},{"key":"hatch_id","value":"265981889265","type":"string","description":"Unique Hatch identifier extracted from prospect URL. The numeric ID at the end of the prospect URL."}]}

Hatch Partner API Documentation (Postman)

Overview

API Demo

Core Flow (Asynchronous)

Authentication

Minimum Required Fields (per prospect)

Enrichment Flags (Partner API)

Usage

What's in a Profile (Typical Fields)

Match Types, Info Accuracy, and the Scorecard

Match Types Reference

Scorecard Field Details

Pragmatic Scoring Tips

Score Definitions

Operational Limits (Design Around These)

IDs & Variables Used in This Collection

Submit Prospects

Endpoint

Auth

Request Body Structure

Minimum Required Fields per Prospect

Request Parameters Description

prospects (array of objects)

callback_url (string)

Response

Get Results (Poll by results_id)

Endpoint

Auth

What you get back

Next Step

Get Prospect Details (Full Profile Fetch)

Endpoint

Auth

When to use

What you get back

Scores

Scorecard

Identity & Summary

Contact

Education

Career

Social Media