> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squid-id.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Enrich Visitor
> Enrich a person by email or phone: full record with direct contact, social, company, organization, job, location, and work history. Charged as one ID match plus one Squid ID+ record.
Provide an **email OR a phone** and get back the **complete** record, including Squid ID+ premium fields (mobile phone, personal email, home address, demographics, and social profiles). Billed as **one ID match plus one Squid ID+ record** at your current rates, on each successful enrichment. Use [Get Visitor Details](/api-reference/visitors/get-details) (free to call) when you only need the base fields on an existing visitor.
Requires **API access** enabled for the website the key belongs to. Squid ID+ does not need to be enabled: the ID+ portion is charged at the discounted rate. Enrichments are **not** added to your visitors dashboard.
## OpenAPI
````yaml openapi.json POST /visitors/enrichment
openapi: 3.0.3
info:
title: Squid ID API (read-only)
version: 1.0.0
description: >-
Read-only API for retrieving an identified visitor by id. Requests go
through the Squid ID broker and authenticate with your Squid ID API key.
servers:
- url: https://id-api.asksquid.ai/api
security:
- BearerAuth: []
paths:
/visitors/enrichment:
post:
summary: Enrich a visitor (full record)
description: >-
Enrich a person by email OR phone and get the full record: person,
direct contact, social, company, organization, job, location, and work
history. Charged as one ID match plus one Squid ID+ record on each
successful enrichment.
operationId: visitors.enrichment
parameters:
- $ref: '#/components/parameters/Authorization'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentRequest'
examples:
email:
summary: Enrich by email
value:
email: john.doe@example.com
phone:
summary: Enrich by phone
value:
phone: '+15551234567'
responses:
'200':
description: Enriched record
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionIdentificationResponse'
'400':
description: Bad request (provide email OR phone)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Insufficient credit, or API access not enabled
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No match found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
components:
parameters:
Authorization:
name: Authorization
in: header
required: true
description: 'Your Squid ID API key, format: `Bearer ` (keys start with `sqid_`).'
schema:
type: string
example: Bearer sqid_xxxxxxxxxxxxxxxxxxxxxxxx
schemas:
EnrichmentRequest:
type: object
description: Provide either email OR phone (but not both)
properties:
email:
type: string
format: email
description: visitor's email address (use email OR phone, not both)
phone:
type: string
description: visitor's phone number (use email OR phone, not both)
forceUpdate:
type: boolean
description: force update even if identity exists
default: false
oneOf:
- required:
- email
not:
required:
- phone
- required:
- phone
not:
required:
- email
ExtensionIdentificationResponse:
type: object
properties:
profile:
type: object
properties:
id:
$ref: '#/components/schemas/ObjectId'
description: Unique identifier. Same id from request
alias:
type: string
description: visitor's alias
email:
type: string
format: email
description: visitor's email address
required:
- id
- alias
- email
traits:
type: object
properties:
id:
type: string
description: Custom identifier. This can be an id from your echo system
example: '00000000000000_0000'
email:
type: string
format: email
description: visitor's primary email
example: john.doe@example.com
full_name:
type: string
description: visitor's full name
example: john doe
first_name:
type: string
description: visitor's first name
example: john
middle_initial:
type: string
description: visitor's middle initial
example: null
middle_name:
type: string
description: visitor's middle name
example: null
last_name:
type: string
description: visitor's last name
example: doe
work_email:
type: string
format: email
description: visitor's work email address
example: john.doe@company.com
recommended_personal_email:
type: string
format: email
description: visitor's recommended personal email address
example: john.doe@example.com
emails:
type: array
description: list of visitor's email addresses with types
items:
type: object
properties:
address:
type: string
format: email
description: email address
example: john.doe@example.com
type:
type: string
enum:
- personal
- current_professional
- professional
description: email type
example: personal
example:
- address: john.doe@example.com
type: personal
- address: john.doe@company.com
type: current_professional
gender:
type: string
description: visitor's gender
example: male
birth_year:
type: integer
description: visitor's birth year
example: 1990
birth_date:
type: string
description: visitor's birth date
example: '1990-05-15'
mobile_phone:
type: string
description: visitor's mobile phone number
example: +1-555-123-4567
phone_numbers:
type: array
description: list of visitor's phone numbers
items:
type: string
example:
- +1-555-123-4567
- +1-555-987-6543
industry:
type: string
description: visitor's industry
example: internet
home_owner:
type: boolean
description: whether visitor is a home owner
example: null
married:
type: boolean
description: whether visitor is married
example: null
children:
type: string
description: information about visitor's children
example: null
email_status:
type: string
description: email verification status
example: null
photo_url:
type: string
format: uri
description: visitor's profile photo URL
example: https://example.com/photos/profile.jpg
extrapolated_email_confidence:
type: number
description: confidence score for extrapolated email
example: null
social:
type: object
properties:
linkedin:
type: object
properties:
id:
type: string
description: LinkedIn profile ID
example: '123456'
url:
type: string
description: LinkedIn profile URL
example: linkedin.com/in/username
username:
type: string
description: LinkedIn username
example: username
facebook:
type: object
properties:
url:
type: string
description: Facebook profile URL
example: facebook.com/username
username:
type: string
description: Facebook username
example: username
twitter:
type: object
properties:
url:
type: string
description: Twitter profile URL
example: twitter.com/username
username:
type: string
description: Twitter username
example: username
github:
type: object
properties:
url:
type: string
description: GitHub profile URL
example: github.com/username
username:
type: string
description: GitHub username
example: username
company:
type: object
properties:
name:
type: string
description: company name
example: acme corp
size:
type: string
description: company size range (e.g., '1-10', '51-200')
example: 51-200
founded:
type: integer
description: year company was founded
example: 2010
industry:
type: string
description: company industry
example: technology
description:
type: string
description: company description
example: a technology company providing innovative solutions
revenue:
type: string
description: company revenue range
example: $10M - $50M
phone_numbers:
type: array
description: company phone numbers
items:
type: string
example:
- +1-555-000-0000
website:
type: string
description: company website
example: example.com
linkedin:
type: object
properties:
url:
type: string
description: company LinkedIn URL
example: linkedin.com/company/example
id:
type: string
description: company LinkedIn ID
example: '12345'
location:
type: object
properties:
name:
type: string
description: full location name
example: main street, city, country
city:
type: string
description: city
example: city
state:
type: string
description: state
example: state
locality:
type: string
description: city or locality
example: city
metro:
type: string
description: metro area
example: null
region:
type: string
description: state or region
example: state
country:
type: string
description: country
example: country
continent:
type: string
description: continent
example: continent
street_address:
type: string
description: street address
example: null
address_line_2:
type: string
description: second address line
example: null
postal_code:
type: string
description: postal code
example: null
geo:
type: string
description: geographic coordinates (latitude,longitude)
example: 40.00,-80.00
organization:
type: object
description: detailed organization/company information
properties:
id:
type: string
description: organization identifier
example: org123456
name:
type: string
description: organization name
example: example company
website_url:
type: string
description: organization website URL
example: www.example.com/
blog_url:
type: string
description: organization blog URL
example: blog.example.com
angellist_url:
type: string
description: AngelList profile URL
example: angel.co/example-company
linkedin_url:
type: string
description: LinkedIn company URL
example: www.linkedin.com/company/example
twitter_url:
type: string
description: Twitter profile URL
example: www.twitter.com/example
facebook_url:
type: string
description: Facebook page URL
example: www.facebook.com/example
primary_phone:
type: object
properties:
number:
type: string
description: primary phone number
example: +1 555-000-0000
source:
type: string
description: source of phone number
example: source
sanitized_number:
type: string
description: sanitized phone number
example: '+15550000000'
languages:
type: array
description: languages supported by organization
items:
type: string
example:
- english
alexa_ranking:
type: integer
description: Alexa ranking
example: null
phone:
type: string
description: organization phone number
example: +1 555-000-0000
linkedin_uid:
type: string
description: LinkedIn unique identifier
example: '123456'
founded_year:
type: integer
description: year organization was founded
example: 2010
publicly_traded_symbol:
type: string
description: stock ticker symbol
example: null
publicly_traded_exchange:
type: string
description: stock exchange
example: null
logo_url:
type: string
description: organization logo URL
example: example.com/logos/company.png
crunchbase_url:
type: string
description: Crunchbase profile URL
example: null
primary_domain:
type: string
description: primary domain name
example: example.com
sic_codes:
type: array
description: Standard Industrial Classification codes
items:
type: string
example:
- '1234'
naics_codes:
type: array
description: North American Industry Classification System codes
items:
type: string
example:
- '12345'
sanitized_phone:
type: string
description: sanitized phone number
example: '+15550000000'
industry:
type: string
description: organization industry
example: technology
estimated_num_employees:
type: integer
description: estimated number of employees
example: 50
keywords:
type: array
description: keywords associated with organization
items:
type: string
example:
- technology
- software
- services
organization_revenue_printed:
type: string
description: formatted revenue string
example: 10m
organization_revenue:
type: integer
description: organization revenue in dollars
example: 10000000
industries:
type: array
description: primary industries
items:
type: string
example:
- technology
secondary_industries:
type: array
description: secondary industries
items:
type: string
example: []
snippets_loaded:
type: boolean
description: whether snippets are loaded
example: true
industry_tag_id:
type: string
description: industry tag identifier
example: 5567cd467369644d39040000
industry_tag_hash:
type: object
description: industry tag hash mapping
example:
technology: tag123456
retail_location_count:
type: integer
description: number of retail locations
example: 0
raw_address:
type: string
description: raw address string
example: 123 main st., suite 100, city, state 12345, country
street_address:
type: string
description: street address
example: 123 main st
city:
type: string
description: city
example: city
state:
type: string
description: state or province
example: state
postal_code:
type: string
description: postal code
example: '12345'
country:
type: string
description: country
example: country
owned_by_organization_id:
type: string
description: parent organization identifier
example: parent123
owned_by_organization:
type: object
description: parent organization details
properties:
id:
type: string
description: parent organization ID
example: parent123
name:
type: string
description: parent organization name
example: parent company
website_url:
type: string
description: parent organization website
example: www.parentcompany.com/
short_description:
type: string
description: organization short description
example: >-
example company is a technology company providing innovative
solutions...
suborganizations:
type: array
description: list of sub-organizations
items:
type: object
example: []
num_suborganizations:
type: integer
description: number of sub-organizations
example: 0
annual_revenue_printed:
type: string
description: formatted annual revenue
example: 10m
annual_revenue:
type: integer
description: annual revenue in dollars
example: 10000000
total_funding:
type: integer
description: total funding raised
example: 5000000
total_funding_printed:
type: string
description: formatted total funding
example: 5m
latest_funding_round_date:
type: string
format: date-time
description: date of latest funding round
example: '2020-01-01t00:00:00.000+00:00'
latest_funding_stage:
type: string
description: latest funding stage
example: series a
funding_events:
type: array
description: funding events history
items:
type: object
properties:
id:
type: string
description: funding event ID
date:
type: string
format: date-time
description: funding date
news_url:
type: string
description: news article URL
type:
type: string
description: funding type (seed, series a, etc)
investors:
type: string
description: investors involved
amount:
type: string
description: funding amount
currency:
type: string
description: currency symbol
example:
- id: event123
date: '2020-01-01T00:00:00.000+00:00'
news_url: example.com/news/funding
type: series a
investors: investor one, investor two
amount: 3m
currency: $
technology_names:
type: array
description: technologies used by organization
items:
type: string
example:
- email
- analytics
- crm
current_technologies:
type: array
description: current technologies with details
items:
type: object
properties:
uid:
type: string
description: technology unique identifier
name:
type: string
description: technology name
category:
type: string
description: technology category
example:
- uid: tech123
name: technology
category: category
org_chart_root_people_ids:
type: array
description: root people IDs in org chart
items:
type: string
example:
- person123
org_chart_sector:
type: string
description: organization chart sector
example: sector
org_chart_removed:
type: boolean
description: whether org chart is removed
example: false
org_chart_show_department_filter:
type: boolean
description: whether to show department filter
example: true
organization_headcount_six_month_growth:
type: number
description: headcount growth over 6 months
example: null
organization_headcount_twelve_month_growth:
type: number
description: headcount growth over 12 months
example: null
organization_headcount_twenty_four_month_growth:
type: number
description: headcount growth over 24 months
example: null
job:
type: object
properties:
title:
type: string
description: job title
example: developer
role:
type: string
description: job role category (e.g., 'engineering', 'sales')
example: engineering
sub_role:
type: string
description: job sub-role
example: null
title_levels:
type: array
description: job title seniority levels
items:
type: string
example: []
income_range:
type: string
description: estimated income range
example: $75k - $100k
net_worth:
type: string
description: estimated net worth
example: $100k - $250k
headline:
type: string
description: job headline
example: senior manager at example company
seniority:
type: string
description: seniority level
example: vp
functions:
type: array
description: job functions
items:
type: string
example:
- operations
departments:
type: array
description: departments
items:
type: string
example:
- master_operations
subdepartments:
type: array
description: subdepartments
items:
type: string
example:
- operations
location:
type: object
properties:
name:
type: string
description: full location name
example: street, city, country
city:
type: string
description: city
example: city
state:
type: string
description: state
example: state
locality:
type: string
description: city or locality
example: city
metro:
type: string
description: metro area
example: null
region:
type: string
description: state or region
example: region
country:
type: string
description: country
example: country
continent:
type: string
description: continent
example: continent
street_address:
type: string
description: street address
example: null
address_line_2:
type: string
description: second address line
example: null
postal_code:
type: string
description: postal code
example: null
geo:
type: string
description: geographic coordinates (latitude,longitude)
example: 40.00,-75.00
last_updated:
type: string
description: date location was last updated
example: null
location_names:
type: array
description: list of location names
items:
type: string
example: []
street_addresses:
type: array
description: list of street addresses
items:
type: object
properties:
name:
type: string
description: full location name
locality:
type: string
description: city or locality
region:
type: string
description: state or region
metro:
type: string
description: metro area
country:
type: string
description: country
continent:
type: string
description: continent
street_address:
type: string
description: street address
address_line_2:
type: string
description: second address line
postal_code:
type: string
description: postal code
geo:
type: string
description: geographic coordinates
example: []
regions:
type: array
description: list of regions associated with visitor
items:
type: string
example: []
experience:
type: array
description: work experience history
items:
type: object
properties:
company:
type: object
properties:
name:
type: string
description: company name
example: example corp
size:
type: string
description: company size range
example: 51-200
id:
type: string
description: company identifier
example: company123
founded:
type: integer
description: year founded
example: 2010
industry:
type: string
description: company industry
example: technology
location:
type: object
properties:
name:
type: string
example: street, city, country
locality:
type: string
example: city
region:
type: string
example: region
metro:
type: string
example: null
country:
type: string
example: country
continent:
type: string
example: continent
street_address:
type: string
example: null
address_line_2:
type: string
example: null
postal_code:
type: string
example: null
geo:
type: string
example: 40.00,-75.00
linkedin_url:
type: string
description: company LinkedIn URL
example: linkedin.com/company/example
linkedin_id:
type: string
description: company LinkedIn ID
example: '12345'
facebook_url:
type: string
description: company Facebook URL
example: facebook.com/example
twitter_url:
type: string
description: company Twitter URL
example: null
website:
type: string
description: company website
example: example.com
location_names:
type: array
description: list of work location names
items:
type: string
example: []
end_date:
type: string
description: employment end date (YYYY-MM format)
example: null
start_date:
type: string
description: employment start date (YYYY-MM format)
example: 2011-10
title:
type: object
properties:
name:
type: string
description: job title
example: developer
role:
type: string
description: job role
example: engineering
sub_role:
type: string
description: job sub-role
example: null
levels:
type: array
description: seniority levels
items:
type: string
example: []
is_primary:
type: boolean
description: whether this is the current/primary position
example: true
example:
- company:
name: previous company
size: null
id: null
founded: null
industry: null
location: null
linkedin_url: null
linkedin_id: null
facebook_url: null
twitter_url: null
website: null
location_names: []
end_date: 2015-06
start_date: 2013-01
title:
name: software engineer
role: engineering
sub_role: null
levels: []
is_primary: false
- company:
name: current company
size: 51-200
id: company123
founded: 2010
industry: technology
location:
name: street, city, country
locality: city
region: region
metro: null
country: country
continent: continent
street_address: null
address_line_2: null
postal_code: null
geo: 40.00,-75.00
linkedin_url: linkedin.com/company/example
linkedin_id: '12345'
facebook_url: facebook.com/example
twitter_url: null
website: example.com
location_names: []
end_date: null
start_date: 2015-07
title:
name: senior engineer
role: engineering
sub_role: null
levels: []
is_primary: true
interests:
type: array
description: visitor's interests
items:
type: string
example: []
skills:
type: array
description: visitor's skills
items:
type: string
example: []
device:
type: object
properties:
type:
type: string
description: device type (e.g., 'desktop', 'mobile', 'tablet')
example: desktop
Error:
type: object
properties:
error:
type: string
message:
type: string
ObjectId:
type: string
description: MongoDB ObjectId as 24 hex characters.
pattern: ^[a-fA-F0-9]{24}$
example: 64fa2b9f1c2a3e4b5d6f7890
securitySchemes:
BearerAuth:
type: http
scheme: bearer
````