curl --request PATCH \
--url https://api.instaview.sk/contact-fields/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "Order reference",
"enumOptions": [
"<string>"
],
"isPii": true,
"csvAliases": [
"<string>"
],
"allowPiiInContext": false,
"description": "<string>",
"displayOrder": 123
}
'import requests
url = "https://api.instaview.sk/contact-fields/{id}"
payload = {
"label": "Order reference",
"enumOptions": ["<string>"],
"isPii": True,
"csvAliases": ["<string>"],
"allowPiiInContext": False,
"description": "<string>",
"displayOrder": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Order reference',
enumOptions: ['<string>'],
isPii: true,
csvAliases: ['<string>'],
allowPiiInContext: false,
description: '<string>',
displayOrder: 123
})
};
fetch('https://api.instaview.sk/contact-fields/{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/contact-fields/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Order reference',
'enumOptions' => [
'<string>'
],
'isPii' => true,
'csvAliases' => [
'<string>'
],
'allowPiiInContext' => false,
'description' => '<string>',
'displayOrder' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/contact-fields/{id}"
payload := strings.NewReader("{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.instaview.sk/contact-fields/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/contact-fields/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"key": "order_number",
"label": "Order number",
"dataType": "string",
"category": "commercial",
"isPii": false,
"isSystem": false,
"allowPiiInContext": false,
"inEssentialPromptSet": false,
"displayOrder": 50,
"isCompanyOverride": false,
"readOnly": false,
"writable": true,
"enumOptions": [
"pricing page",
"webinar",
"referral"
],
"csvAliases": [
"Order #",
"OrderNo"
],
"description": "The order this call is about"
}Update Contact Field
Changes one of your own fields. Everything is editable except the key, which is fixed once the field exists. Seeded fields cannot be edited at all.
curl --request PATCH \
--url https://api.instaview.sk/contact-fields/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "Order reference",
"enumOptions": [
"<string>"
],
"isPii": true,
"csvAliases": [
"<string>"
],
"allowPiiInContext": false,
"description": "<string>",
"displayOrder": 123
}
'import requests
url = "https://api.instaview.sk/contact-fields/{id}"
payload = {
"label": "Order reference",
"enumOptions": ["<string>"],
"isPii": True,
"csvAliases": ["<string>"],
"allowPiiInContext": False,
"description": "<string>",
"displayOrder": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Order reference',
enumOptions: ['<string>'],
isPii: true,
csvAliases: ['<string>'],
allowPiiInContext: false,
description: '<string>',
displayOrder: 123
})
};
fetch('https://api.instaview.sk/contact-fields/{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/contact-fields/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Order reference',
'enumOptions' => [
'<string>'
],
'isPii' => true,
'csvAliases' => [
'<string>'
],
'allowPiiInContext' => false,
'description' => '<string>',
'displayOrder' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/contact-fields/{id}"
payload := strings.NewReader("{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.instaview.sk/contact-fields/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/contact-fields/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Order reference\",\n \"enumOptions\": [\n \"<string>\"\n ],\n \"isPii\": true,\n \"csvAliases\": [\n \"<string>\"\n ],\n \"allowPiiInContext\": false,\n \"description\": \"<string>\",\n \"displayOrder\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"key": "order_number",
"label": "Order number",
"dataType": "string",
"category": "commercial",
"isPii": false,
"isSystem": false,
"allowPiiInContext": false,
"inEssentialPromptSet": false,
"displayOrder": 50,
"isCompanyOverride": false,
"readOnly": false,
"writable": true,
"enumOptions": [
"pricing page",
"webinar",
"referral"
],
"csvAliases": [
"Order #",
"OrderNo"
],
"description": "The order this call is about"
}Overview
Everything about a field is editable except its key. Relabel it, retype it, add CSV aliases, switch it in or out of the agent’s contact summary, reorder it.// Relabel
PATCH /contact-fields/{id}
{
"label": "Order reference"
}
// Turn a loose string into a closed set
PATCH /contact-fields/{id}
{
"dataType": "enum",
"enumOptions": ["pricing page", "webinar", "referral"]
}
// Start volunteering it to the agent
PATCH /contact-fields/{id}
{
"isPii": true,
"allowPiiInContext": true
}
// Match two more CSV headers on import
PATCH /contact-fields/{id}
{
"csvAliases": ["Order #", "OrderNo"]
}
The key is not editable
There is nokey property on this request. Sending one is a 400 naming it, rather than a
silent no-op.
The reason is that a key is the identity of two things that cannot be migrated in the same
step: every {{contact.<key>}} token already saved inside an agent’s flow, and every value
already stored under that key on your contacts. A rename would blank the first and orphan the
second. To change a key,
create a new field, copy the values
across, update your agents, then
delete the old one.
Seeded fields cannot be edited
A field withisSystem: true belongs to the platform — editing it would change what
{{contact.first_name}} means for every company. PATCH on one is a 403. To change a seeded
field’s label or type for your company alone, define your own field with the same key: it
shadows the seeded one and comes back with isCompanyOverride: true.
Changing a type
ChangingdataType changes how future writes are validated. It does not re-validate or
convert values already stored — those keep whatever they were written as. If you are tightening
a field (say string to enum), read the existing values first.
Moving away from enum clears enumOptions automatically, so a field cannot keep a stale
option list that validation would then enforce against a string.
tags is worth calling out for the same reason: switching a string field to tags leaves
every stored value a plain string until it is next written, so a reader has to handle both
until then. Writing "a, b" to it once turns that contact’s value into ["a","b"].
Scopes
write:contacts (or its write:candidates alias).
Error Scenarios
- 400 Bad Request: a
keyproperty; anenumleft with no options - 403 Forbidden: a seeded field; or the key lacks
write:contacts - 404 Not Found: no such field in your company’s catalog
Related Resources
List Contact Fields
Create Contact Field
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.
Body
Human label
"Order reference"
The value type. Changing it does not re-validate values already stored — those keep whatever they were written as. tags stores a string[] and accepts either an array or a comma-separated string, so one CSV cell maps onto one field.
string, number, date, bool, enum, tags The allowed values. Cleared automatically when the type moves away from ENUM.
Mark the field as personal data. Personal data. Masked in logs, and EXCLUDED from everything that reaches the agent — the prompt and the generated contact document alike — unless allowPiiInContext is set on this field, or the platform lists it in the essential prompt set (inEssentialPromptSet).
Extra CSV header names this field should also match Stored for the contact-field importer, which has not shipped: setting this changes no import behaviour today.
Let this one personal field reach the agent anyway. It joins the generated contact document AND the prompt, because a queryable value is one the agent might never think to look up, and reliability is the point for a field like an outstanding balance. Only meaningful when isPii is true; sending it on a field that is not personal data is rejected rather than ignored.
false
What the field means
300Ascending display order; ties break on key
Response
Field id. Needed only to address PATCH and DELETE; every other surface uses key.
"123e4567-e89b-12d3-a456-426614174000"
The key you address this field by, in {{contact.<key>}} and in a values payload
"order_number"
Human label, shown wherever the field is offered for editing
"Order number"
The value type this field accepts. Writes are validated against it. tags is a string[] and accepts either an array or a comma-separated string, so one CSV cell maps onto one field.
string, number, date, bool, enum, tags "string"
Which panel of the catalog this field belongs to — the grouping the dashboard's variable palette uses, and the first key this list is ordered by. Set by InstaView and not writable: a field you define is always custom, and a field of yours that shadows a seeded one reports the seeded field's category so the grouping is the same for every company.
identity, organisation, commercial, relationship, scheduling, recruiting, platform, custom "commercial"
Personal data. Masked in logs, and EXCLUDED from everything that reaches the agent — the prompt and the generated contact document alike — unless allowPiiInContext is set on this field, or the platform lists it in the essential prompt set (inEssentialPromptSet).
false
A field the platform defines and every company shares. A seeded field cannot be edited or deleted directly; for most of them you can define your own field with the same key to override the label and type for your company alone. Eight keys are RESERVED and refuse even that (first_name, last_name, email, phone, company_name, company_description, agent_name, profile), because the platform resolves them itself.
false
Let this one personal field reach the agent anyway. It joins the generated contact document AND the prompt, because a queryable value is one the agent might never think to look up, and reliability is the point for a field like an outstanding balance. Only meaningful when isPii is true; sending it on a field that is not personal data is rejected rather than ignored.
false
Read-only. Whether the platform puts this field in every context-enabled agent's prompt: a short set covering what an agent needs to open a call correctly. Not settable — everything else the contact has reaches the agent through the generated contact document instead, which is queried mid-call rather than paid for on every dial.
false
Ascending display order; ties break on key
50
True when this is your own field overriding a seeded field of the same key
false
Catalogued so an agent author can use the token, but resolved by the platform on every call rather than stored per contact (company_description is your company's own blurb, not the contact's data). Sending a value for one is a 422. Note this is not the whole of what you can write — check writable for that.
false
Whether fields on POST /contacts or PATCH /contacts/{id} accepts a value for this key. The one flag to branch on before writing: readOnly alone is not enough, because a key the platform RESERVES (email, first_name, phone and the rest of the identity fields) reports readOnly: false and is still refused with a 422 — those are writable, but through the contact resource's own properties rather than as a field. False also for every read-only key, so a false here always means "do not send a value for this".
true
The allowed values, for an ENUM field. Absent for every other type.
["pricing page", "webinar", "referral"]
Extra CSV header names this field also matches during an import Stored for the contact-field importer, which has not shipped: setting this changes no import behaviour today.
["Order #", "OrderNo"]
What the field means
"The order this call is about"