curl --request GET \
--url https://api.instaview.sk/contacts/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/contacts/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/contacts/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/contacts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/contacts/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/contacts/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/contacts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"status": "APPLIED",
"fields": {
"order_number": "SO-40128",
"is_vip": true,
"renewal_date": "2026-04-01"
},
"createdAt": "2025-11-20T10:30:00Z",
"updatedAt": "2025-11-20T10:30:00Z",
"jobId": "987e6543-e21b-12d3-a456-426614174000",
"jobIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"email": "john.doe@example.com",
"phoneNumber": "+421915123456",
"gdprExpiryDate": "2026-11-16",
"overallRating": 85,
"metadata": {
"source": "LinkedIn",
"externalId": "CAND-12345"
},
"analysisCount": 2,
"interviewCount": 3,
"links": {
"analyses": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/analyses",
"interviews": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/conversations"
},
"gender": "female",
"anonymizedCvText": "[NAME]\nSoftware Engineer\nExperience: ...",
"workHistory": [
{
"companyName": "Google",
"candidatePosition": "Software Engineer",
"referencePhone": "+1987654321",
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceName": "Jane Smith",
"startDate": "2020-01-01",
"endDate": "2022-12-31"
}
]
}Get Contact
Returns a single contact, ensuring the contact (and any job associations) belong to the API key’s company.
curl --request GET \
--url https://api.instaview.sk/contacts/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/contacts/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/contacts/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/contacts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/contacts/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/contacts/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/contacts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"status": "APPLIED",
"fields": {
"order_number": "SO-40128",
"is_vip": true,
"renewal_date": "2026-04-01"
},
"createdAt": "2025-11-20T10:30:00Z",
"updatedAt": "2025-11-20T10:30:00Z",
"jobId": "987e6543-e21b-12d3-a456-426614174000",
"jobIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"email": "john.doe@example.com",
"phoneNumber": "+421915123456",
"gdprExpiryDate": "2026-11-16",
"overallRating": 85,
"metadata": {
"source": "LinkedIn",
"externalId": "CAND-12345"
},
"analysisCount": 2,
"interviewCount": 3,
"links": {
"analyses": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/analyses",
"interviews": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/conversations"
},
"gender": "female",
"anonymizedCvText": "[NAME]\nSoftware Engineer\nExperience: ...",
"workHistory": [
{
"companyName": "Google",
"candidatePosition": "Software Engineer",
"referencePhone": "+1987654321",
"id": "123e4567-e89b-12d3-a456-426614174000",
"referenceName": "Jane Smith",
"startDate": "2020-01-01",
"endDate": "2022-12-31"
}
]
}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.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 (
jobIdandjobIds) - 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.<key>}} |
| Written by | POST / PATCH /contacts | POST / PATCH /contacts, as fields |
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.
analysisCount, interviewCount and links. Nothing populates them, so treat them as absent
rather than as zero — and count conversations with 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 returns403.
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
Contacts Resource Guide
Update Contact
List Contacts
Authorizations
API key for authentication using Bearer scheme
Path Parameters
Query Parameters
Required for ATS API keys to specify which company to access. Ignored for standard company API keys.
Response
Contact ID
"123e4567-e89b-12d3-a456-426614174000"
The contact's first name
"John"
The contact's last name
"Doe"
Contact status
UNDEFINED, APPLIED, IN_PROCESS, REJECTED, ACCEPTED "APPLIED"
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.<key>}}. 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.
{
"order_number": "SO-40128",
"is_vip": true,
"renewal_date": "2026-04-01"
}
Created timestamp (UTC)
"2025-11-20T10:30:00Z"
Updated timestamp (UTC)
"2025-11-20T10:30:00Z"
[Deprecated] Single job ID; use jobIds instead.
"987e6543-e21b-12d3-a456-426614174000"
Jobs the contact is assigned to.
50The contact's email address
"john.doe@example.com"
The contact's phone number
"+421915123456"
GDPR expiry date. Currently returned as a date (no time). NOTE: We plan to migrate to a timestamp with timezone (timestamptz) for global correctness.
"2026-11-16"
Overall rating/match score (0-100)
0 <= x <= 10085
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.
{
"source": "LinkedIn",
"externalId": "CAND-12345"
}
Number of analyses for this contact. Not currently populated by any endpoint — treat as absent.
2
Number of conversations for this contact. Keeps its original field name, and is not currently populated by any endpoint — treat as absent.
3
Convenience links to related collections. Endpoints may be added incrementally.
{
"analyses": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/analyses",
"interviews": "/v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/conversations"
}
The contact's gender. Used for gender-aware addressing on the call. Null if not explicitly set (auto-detected from the name).
male, female "female"
The contact's anonymized CV in plain text.
"[NAME]\nSoftware Engineer\nExperience: ..."
Work history items for the contact.
20Show child attributes
Show child attributes