> ## 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.
# Get Contact
> Returns a single contact, ensuring the contact (and any job associations) belong to the API key's company.
`GET /candidates/{id}` 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).
Retrieves a single contact by ID, with their details, status and job associations.
## Overview
This endpoint returns everything held about one contact: their name, how to reach them, their status, the jobs they are associated with, and your own metadata. Use it before starting a conversation, or before an update.
## Use Cases
* **Display a profile**: show everything you hold about someone in your own UI
* **Pre-flight check**: confirm the contact exists and is reachable by your key before creating a conversation
* **Status checking**: read where they have got to in your process
* **Reconciliation**: confirm the record matches your other systems
## Response Data
The response includes:
* Name, email and phone number
* Job associations (`jobId` and `jobIds`)
* Current status
* Gender, if set — used for gender-aware addressing on the call
* Metadata (anything of your own: resume URL, LinkedIn, an external id)
* `fields` — the contact's catalogued field values, keyed by field key
* Timestamps (created, updated)
### `fields` vs `metadata`
Stored separately on the same contact, and only one of them reaches an agent.
| | `metadata` | `fields` |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
| What it is | your own scratch space | values defined in your company catalog |
| Validated | no | yes — against each field's type and enum |
| An agent can say it | **no** | yes, as `{{contact.}}` |
| Written by | `POST` / `PATCH /contacts` | `POST` / `PATCH /contacts`, as [`fields`](/api-reference/contacts/update-contact#updating-field-values) |
A field with no value is absent from `fields` rather than `null`, and `{}` means none are set.
A value whose definition has since been deleted is omitted too — the data survives the delete and
reappears if you define the key again. The catalog itself is
[`GET /contact-fields`](/api-reference/contact-fields/list-contact-fields).
Three fields are declared on the contact schema but **not currently returned** by any endpoint:
`analysisCount`, `interviewCount` and `links`. Nothing populates them, so treat them as absent
rather than as zero — and count conversations with [List
Conversations](/api-reference/conversations/list-conversations) instead. `interviewCount` also
keeps its original name; it was never given a neutral alias.
## Company Isolation
You can only read contacts belonging to your API key's company. Anything else returns `403`.
## Error Scenarios
* **404 Not Found**: the contact does not exist, or has been deleted
* **403 Forbidden**: the contact belongs to a different company
## Related Resources
Learn the contact structure and its status workflow
Change a contact's details
Browse your contacts
## OpenAPI
````yaml GET /contacts/{id}
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/{id}:
get:
tags:
- Contacts
summary: Get contact by ID
description: >-
Returns a single contact, ensuring the contact (and any job
associations) belong to the API key's company.
operationId: PublicCandidatesController_getCandidateById_v1
parameters:
- name: id
required: true
in: path
schema:
type: string
format: uuid
- name: companyId
required: false
in: query
description: >-
Required for ATS API keys to specify which company to access.
Ignored for standard company API keys.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCandidateDto'
security:
- bearer: []
components:
schemas:
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
````