400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The import rule applies: consent starts as "unknown" and the contact gets no campaigns until they message the bot themselves. Telegram bots need external_id (the numeric chat ID); on WhatsApp bots, phone is used when external_id is missing. An existing channel ID returns 409 contact_exists. Needs admin permission. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
Body fields
Name
Type
Required
Description
bot_id
uuid
yes
external_id
string
no
len ≤ 64
name
string
no
len ≤ 120
username
string
no
len ≤ 64
phone
string
no
len ≤ 32
tags
string[]
no
items ≤ 20
notes
string
no
len ≤ 4000
attributes
object
no
Custom field key → value (text, number, YYYY-MM-DD date or option)
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.contact_exists
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
tags replaces the whole list; add_tags / remove_tags only add or remove. attributes only accepts fields defined in the dashboard; null clears a field. Scope: write.
Scope
write
SDK method
updateContact · update_contact
MCP tool
updateContact
Parameters
Name
Type
Required
Description
idpath
uuid
yes
Contact ID
Body fields
Name
Type
Required
Description
name
string | null
no
len ≤ 120
notes
string | null
no
len ≤ 4000
tags
string[]
no
items ≤ 20
add_tags
string[]
no
items ≤ 20
remove_tags
string[]
no
items ≤ 20
attributes
object
no
fields ≤ 30
Example request
curl -X PATCH "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Jane Smith","add_tags":["vip"],"notes":"Asked for a business quote"}'
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The contact, their conversations, messages and other linked personal data are deleted irreversibly. The audit log keeps only a hash of the channel ID. Needs admin permission. Scope: contacts:write.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The change is written to the consent ledger with source "api". If given, tags replaces the whole tag list of the contact; use add_tags on updateContact to only add. Scope: write.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Up to 2 MB and 5,000 rows; the delimiter can be a semicolon, comma or tab. New contacts start with "unknown" consent; an existing contact's consent can only move to opted out, filled values are kept and tags are merged. Custom field columns match by key or label. errors returns up to 20 rows. Needs admin permission. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Each page holds up to 1000 contacts. Every row ends in CRLF; the BOM and header are on the first page only, so appending the csv chunks in order gives a single file. Cells starting with = + - @ are escaped against formula injection. Each page is written to the audit log. Needs admin permission. Scope: contacts:read.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
tag_add, tag_remove, opt_out or delete, for up to 200 contacts at once. delete is irreversible and needs admin permission. Members only affect contacts of bots they can access; other IDs are silently left out, and affected is the number actually changed. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
You need access to both records' bots; an inaccessible other record returns 404. If they can't be linked it returns 409 profile_link_failed, and 409 feature_disabled when the "profile" feature is off. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.profile_link_failedfeature_disabled
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The record isn't deleted. Returns 409 not_linked if it isn't in a profile, and 409 feature_disabled when the "profile" feature is off. Scope: contacts:write.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.not_linkedfeature_disabled
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Applies to every contact in the organization; matching ignores case. Automation steps and campaign segments don't change automatically. Needs admin permission. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Up to 50 tags at once. Applies to every contact in the organization; automation steps and campaign segments don't change automatically. Needs admin permission. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Up to 30 fields (409 limit_reached); an existing key returns 409 field_exists. key starts with a lowercase letter and uses a–z, 0–9 and _; system keys such as ad or telefon can't be used. options is required only for the secim type. AI write access starts off. Needs admin permission. Scope: contacts:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
409The action isn't possible in this state; the code gives the reason.limit_reachedfield_exists
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The key and type don't change; options applies to the secim type only. Contacts holding a removed option lose that value (cleared_contacts). ai_writable lets the AI save tool write to this field. Needs admin permission. Scope: contacts:write.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.