> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.
# List Contacts
> Lists the contacts that belong to the API key's company, whether or not they hold job assignments.
`GET /candidates` is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See [Resource names](/api-reference/introduction#resource-names).
Lists your contacts, with pagination and filtering.
## Overview
This endpoint returns the contacts belonging to your API key's company. You can filter by job or status, search by name or email, and page through the results — useful for finding someone before starting a conversation with them.
## Use Cases
* **Browse your contacts**: review everyone your company holds
* **Job-specific filtering**: narrow to the contacts assigned to one job
* **Status tracking**: filter by where someone has got to in your process
* **Search**: locate a contact by name or email
## Basic Usage
```javascript theme={null}
// List all contacts (first page, 20 items)
GET /contacts
```
## With Filters
```javascript theme={null}
// Filter by job
GET /contacts?jobId=job-uuid
// Filter by status
GET /contacts?status=IN_PROCESS
// Search by name or email
GET /contacts?search=jane@example.com
// Combine filters with pagination
GET /contacts?jobId=job-uuid&status=APPLIED&page=1&limit=50
```
`status` is one of `UNDEFINED`, `APPLIED`, `IN_PROCESS`, `REJECTED` or `ACCEPTED`. The names
are hiring-flavoured because they predate the neutral vocabulary; they are the values the API
accepts, so they are unchanged.
## Company Scoping
Every contact returned belongs to your API key's company. Contacts from other companies are filtered out.
## Related Resources
Learn about managing contacts, status workflows, and filtering
Understand pagination best practices
Retrieve a single contact by ID
## OpenAPI
````yaml GET /contacts
openapi: 3.0.0
info:
title: InstaView API
description: |-
InstaView API Documentation
## Authentication
All endpoints require API key authentication using Bearer token:
```
Authorization: Bearer sk_your_api_key_here
```
## API Key Management
The API Key module provides comprehensive key management for:
- **Direct Client Keys**: Company-scoped keys for your applications
- **ATS Partner Keys**: Resource-scoped keys for ATS integrations
### Key Features
- HMAC-SHA256 hashing for API key storage
- Configurable rate limiting
- Comprehensive audit logging
- Company-level isolation
- Resource scoping for ATS partners
version: 1.0.0
contact: {}
servers:
- url: https://api.instaview.sk
description: Production API Gateway
security: []
tags: []
paths:
/contacts:
get:
tags:
- Contacts
summary: List contacts
description: >-
Lists the contacts that belong to the API key's company, whether or not
they hold job assignments.
operationId: PublicCandidatesController_listCandidates_v1
parameters:
- name: page
required: false
in: query
description: Page number (1-based)
schema:
minimum: 1
maximum: 10000
default: 1
example: 1
type: integer
- name: limit
required: false
in: query
description: Number of items per page
schema:
minimum: 1
maximum: 100
default: 20
example: 20
type: integer
- name: companyId
required: false
in: query
description: Company ID (required for ATS keys, optional for regular keys)
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: jobId
required: false
in: query
description: Filter by job ID
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: status
required: false
in: query
description: Filter by contact status
schema:
example: APPLIED
type: string
enum:
- UNDEFINED
- APPLIED
- IN_PROCESS
- REJECTED
- ACCEPTED
- name: search
required: false
in: query
description: Search by name (first or last name)
schema:
example: John
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicListCandidatesResponseDto'
security:
- bearer: []
components:
schemas:
PublicListCandidatesResponseDto:
type: object
properties:
data:
description: Array of contacts
type: array
items:
$ref: '#/components/schemas/PublicCandidateDto'
total:
type: number
description: Total number of items
example: 150
page:
type: number
description: Current page number
example: 1
limit:
type: number
description: Number of items per page
example: 20
totalPages:
type: number
description: Total number of pages
example: 8
required:
- data
- total
- page
- limit
- totalPages
PublicCandidateDto:
type: object
properties:
id:
type: string
description: Contact ID
example: 123e4567-e89b-12d3-a456-426614174000
jobId:
type: string
description: '[Deprecated] Single job ID; use jobIds instead.'
deprecated: true
example: 987e6543-e21b-12d3-a456-426614174000
jobIds:
type: array
description: Jobs the contact is assigned to.
items:
type: string
format: uuid
uniqueItems: true
maxItems: 50
firstName:
type: string
description: The contact's first name
example: John
lastName:
type: string
description: The contact's last name
example: Doe
email:
type: string
description: The contact's email address
example: john.doe@example.com
phoneNumber:
type: string
description: The contact's phone number
example: '+421915123456'
status:
type: string
description: Contact status
enum:
- UNDEFINED
- APPLIED
- IN_PROCESS
- REJECTED
- ACCEPTED
example: APPLIED
gdprExpiryDate:
type: string
description: >-
GDPR expiry date. Currently returned as a date (no time). NOTE: We
plan to migrate to a timestamp with timezone (timestamptz) for
global correctness.
example: '2026-11-16'
format: date
overallRating:
type: number
description: Overall rating/match score (0-100)
example: 85
minimum: 0
maximum: 100
metadata:
type: object
description: >-
Your own scratch space on the contact: free-form, unvalidated, and
never read by an agent. Replaced wholesale on update. Not the place
for values you want an agent to say — those are `fields`.
example:
source: LinkedIn
externalId: CAND-12345
fields:
type: object
description: >-
The contact's catalogued field values, keyed by field key — the
counterpart of `metadata`, and the only half an agent can speak.
Each key is defined in the company catalog (`GET /contact-fields`)
and addressable in a flow as `{{contact.}}`. Written through
`fields` on `POST /contacts` and `PATCH /contacts/{id}`, never
through `metadata`. A field with no value is absent rather than
null; `{}` means none are set.
example:
order_number: SO-40128
is_vip: true
renewal_date: '2026-04-01'
additionalProperties: true
createdAt:
type: string
description: Created timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
updatedAt:
type: string
description: Updated timestamp (UTC)
example: '2025-11-20T10:30:00Z'
format: date-time
analysisCount:
type: number
description: >-
Number of analyses for this contact. Not currently populated by any
endpoint — treat as absent.
example: 2
interviewCount:
type: number
description: >-
Number of conversations for this contact. Keeps its original field
name, and is not currently populated by any endpoint — treat as
absent.
example: 3
links:
type: object
description: >-
Convenience links to related collections. Endpoints may be added
incrementally.
example:
analyses: /v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/analyses
interviews: >-
/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/conversations
gender:
type: string
description: >-
The contact's gender. Used for gender-aware addressing on the call.
Null if not explicitly set (auto-detected from the name).
enum:
- male
- female
nullable: true
example: female
anonymizedCvText:
type: string
description: The contact's anonymized CV in plain text.
example: |-
[NAME]
Software Engineer
Experience: ...
workHistory:
type: array
description: Work history items for the contact.
maxItems: 20
items:
$ref: '#/components/schemas/PublicCandidateWorkHistoryItemDto'
required:
- id
- firstName
- lastName
- status
- fields
- createdAt
- updatedAt
PublicCandidateWorkHistoryItemDto:
type: object
properties:
id:
type: string
description: Work history item ID
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
companyName:
type: string
description: Name of the employer company
example: Google
minLength: 1
maxLength: 255
candidatePosition:
type: string
description: >-
The role held at that company. Keeps its original field name, which
is the name the API accepts.
example: Software Engineer
minLength: 1
maxLength: 255
referenceName:
type: string
description: Name of the reference person
example: Jane Smith
maxLength: 255
referencePhone:
type: string
description: Phone number of reference contact in E.164 format
example: '+1987654321'
pattern: ^\+[1-9]\d{1,14}$
startDate:
type: string
description: Job start date in calendar format (yyyy-MM-dd)
example: '2020-01-01'
format: date
pattern: ^\d{4}-\d{2}-\d{2}$
endDate:
type: string
description: Job end date in calendar format (yyyy-MM-dd)
example: '2022-12-31'
format: date
pattern: ^\d{4}-\d{2}-\d{2}$
required:
- companyName
- candidatePosition
- referencePhone
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````