OpenAPI Specification
openapi: 3.0.3
info:
title: UpLead Account Lists API
description: REST API for accessing UpLead's B2B contact and company database. Supports company search and enrichment, person search and enrichment, combined person-and-company lookup, prospector search for discovering contacts by title or function, email verification, credit balance checking, and list management.
version: 2.0.0
contact:
name: UpLead Support
url: https://www.uplead.com/contact/
termsOfService: https://www.uplead.com/terms/
license:
name: Proprietary
servers:
- url: https://api.uplead.com/v2
description: UpLead API v2
- url: https://logo.uplead.com
description: UpLead Logo CDN
security:
- ApiKeyAuth: []
tags:
- name: Lists
description: Contact list management operations.
paths:
/lists:
get:
operationId: getLists
summary: Get paginated contact lists
description: Returns all contact lists for the authenticated account with optional text filter.
tags:
- Lists
parameters:
- name: text
in: query
schema:
type: string
- name: page
in: query
schema:
type: integer
default: 1
- name: per_page
in: query
schema:
type: string
default: '15'
responses:
'200':
description: Paginated list of contact lists.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ListRecord'
meta:
$ref: '#/components/schemas/PaginationMeta'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createList
summary: Create a new contact list
tags:
- Lists
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
responses:
'200':
description: Created list record.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecord'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/lists/{list_id}:
get:
operationId: getList
summary: Retrieve a single contact list
tags:
- Lists
parameters:
- name: list_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Single list record.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecord'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: deleteList
summary: Delete a contact list
tags:
- Lists
parameters:
- name: list_id
in: path
required: true
schema:
type: string
responses:
'200':
description: List deleted successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
nullable: true
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/lists/{list_id}/contacts:
get:
operationId: getListContacts
summary: Retrieve contacts in a list
tags:
- Lists
parameters:
- name: list_id
in: path
required: true
schema:
type: string
- name: text
in: query
schema:
type: string
- name: page
in: query
schema:
type: integer
default: 1
- name: per_page
in: query
schema:
type: string
responses:
'200':
description: Paginated contact results for the list.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/PersonRecord'
meta:
$ref: '#/components/schemas/PaginationMeta'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/lists/{list_id}/contacts/add:
post:
operationId: addContactsToList
summary: Add contacts to a list
tags:
- Lists
parameters:
- name: list_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- contact_ids
properties:
contact_ids:
type: array
items:
type: string
responses:
'200':
description: Updated list record.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecord'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/lists/{list_id}/contacts/delete:
delete:
operationId: deleteContactsFromList
summary: Delete contacts from a list
tags:
- Lists
parameters:
- name: list_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- contact_ids
properties:
contact_ids:
type: array
items:
type: string
responses:
'200':
description: Updated list record after contact removal.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecord'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ListRecord:
type: object
properties:
id:
type: string
name:
type: string
contacts_count:
type: integer
PersonRecord:
type: object
description: Person/contact data record from UpLead's database.
properties:
id:
type: string
description: Internal UpLead person ID.
first_name:
type: string
last_name:
type: string
title:
type: string
job_function:
type: string
enum:
- advisory
- analyst
- creative
- education
- engineering
- finance
- fulfillment
- health
- hospitality
- human resources
- legal
- manufacturing
- marketing
- operations
- partnerships
- product
- professional service
- public service
- research
- sales
- sales engineering
- support
- trade
- unemployed
job_sub_function:
type: string
management_level:
type: string
enum:
- M
- D
- VP
- C
description: M=Manager, D=Director, VP=Vice President, C=C-Suite
gender:
type: string
email:
type: string
format: email
email_status:
type: string
enum:
- valid
- invalid
- accept_all
- unknown
phone_number:
type: string
mobile_directdial:
type: string
city:
type: string
state:
type: string
county:
type: string
country:
type: string
linkedin_url:
type: string
format: uri
industry:
type: string
domain:
type: string
company_name:
type: string
PaginationMeta:
type: object
properties:
total:
type: integer
page:
type: integer
next_page:
type: integer
nullable: true
previous_page:
type: integer
nullable: true
first_page:
type: boolean
last_page:
type: boolean
ErrorResponse:
type: object
properties:
error:
type: string
description: Human-readable error message.
status:
type: integer
description: HTTP status code.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: Your UpLead API key passed as a header value.