The Seamless.AI Contacts API provides programmatic access to contact search, enrichment, and research capabilities. Search for B2B contacts by name, company, title, and location. Enrich existing contact records with emails, phone numbers, and job history. Access job-change intelligence to identify contacts that have recently changed roles.
openapi: 3.0.3
info:
title: Seamless.AI Contacts API
description: >-
The Seamless.AI Contacts API provides programmatic access to B2B contact search,
enrichment, and research capabilities. Search for contacts by name, company, title,
and location, and enrich existing records with verified emails, phone numbers, and
job history using AI-powered data verification.
version: 1.0.0
contact:
url: https://seamless.ai/customers/education/articles/seamless-ai-api-overview
termsOfService: https://seamless.ai/legal/terms-of-service
servers:
- url: https://api.seamless.ai
description: Seamless.AI API
security:
- apiKey: []
paths:
/v1/contacts/search:
post:
operationId: searchContacts
summary: Search Contacts
description: >-
Search for B2B contacts using criteria such as name, company, title, location,
industry, and other filters. Returns paginated search results with contact
identifiers that can be used for enrichment.
tags:
- Contacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSearchRequest'
responses:
'200':
description: Successful contact search results
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSearchResponse'
'401':
description: Unauthorized - invalid or missing API key
'429':
description: Rate limit exceeded - 60 requests per minute per endpoint
/v1/contacts/research:
post:
operationId: researchContact
summary: Research Contact
description: >-
Research a specific contact using a search result ID from /contacts/search
or a direct contact identifier. Returns full contact data including verified
email addresses, phone numbers, job history, and social profiles.
tags:
- Contacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactResearchRequest'
responses:
'200':
description: Full contact research data
content:
application/json:
schema:
$ref: '#/components/schemas/ContactRecord'
'401':
description: Unauthorized
'429':
description: Rate limit exceeded
/v1/contacts/enrich:
post:
operationId: enrichContact
summary: Enrich Contact
description: >-
Enrich an existing contact record with updated or missing fields. Provide
known contact identifiers and receive back verified emails, direct dials,
mobile numbers, job titles, and company information.
tags:
- Contacts
- Enrichment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactEnrichRequest'
responses:
'200':
description: Enriched contact data
content:
application/json:
schema:
$ref: '#/components/schemas/ContactRecord'
'401':
description: Unauthorized
'429':
description: Rate limit exceeded
/v1/contacts/job-changes:
get:
operationId: listContactJobChanges
summary: List Contact Job Changes
description: >-
Retrieve contacts that have recently changed jobs within your contact database.
Returns job-change intelligence including previous and current roles to help
identify warm outreach opportunities.
tags:
- Contacts
- Job Changes
parameters:
- name: page
in: query
description: Page number for paginated results
schema:
type: integer
default: 1
- name: per_page
in: query
description: Number of results per page (max 100)
schema:
type: integer
default: 25
maximum: 100
- name: days
in: query
description: Number of days to look back for job changes
schema:
type: integer
default: 30
responses:
'200':
description: List of contacts with recent job changes
content:
application/json:
schema:
$ref: '#/components/schemas/JobChangesResponse'
'401':
description: Unauthorized
'429':
description: Rate limit exceeded
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: API key in the format "Bearer {api_key}"
schemas:
ContactSearchRequest:
type: object
properties:
name:
type: string
description: Contact full name or partial name
company:
type: string
description: Company name to filter contacts
title:
type: string
description: Job title or keyword
location:
type: string
description: City, state, or country
industry:
type: string
description: Industry vertical
page:
type: integer
default: 1
description: Page number for pagination
per_page:
type: integer
default: 25
maximum: 100
description: Results per page
ContactSearchResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContactSearchResult'
meta:
$ref: '#/components/schemas/PaginationMeta'
supplementalData:
type: object
properties:
nextToken:
type: string
description: Token for next page of results
ContactSearchResult:
type: object
properties:
searchResultId:
type: string
description: Unique identifier for use in research/enrichment calls
name:
type: string
description: Contact full name
company:
type: string
description: Current employer
title:
type: string
description: Current job title
location:
type: string
description: Geographic location
ContactResearchRequest:
type: object
properties:
searchResultId:
type: string
description: Search result ID from /contacts/search
email:
type: string
description: Known email address for lookup
linkedinUrl:
type: string
description: LinkedIn profile URL
ContactEnrichRequest:
type: object
properties:
email:
type: string
description: Email address to enrich
name:
type: string
description: Contact full name
company:
type: string
description: Company name
linkedinUrl:
type: string
description: LinkedIn profile URL
ContactRecord:
type: object
properties:
id:
type: string
description: Unique contact identifier
name:
type: string
description: Full name
firstName:
type: string
lastName:
type: string
title:
type: string
description: Current job title
company:
type: string
description: Current employer name
emails:
type: array
items:
type: object
properties:
email:
type: string
type:
type: string
enum: [work, personal]
verified:
type: boolean
phones:
type: array
items:
type: object
properties:
number:
type: string
type:
type: string
enum: [direct, mobile, office]
location:
type: string
linkedinUrl:
type: string
jobHistory:
type: array
items:
type: object
properties:
company:
type: string
title:
type: string
startDate:
type: string
endDate:
type: string
JobChangesResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
contactId:
type: string
name:
type: string
previousCompany:
type: string
previousTitle:
type: string
currentCompany:
type: string
currentTitle:
type: string
changeDate:
type: string
format: date
meta:
$ref: '#/components/schemas/PaginationMeta'
PaginationMeta:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
total_pages:
type: integer