API reference

Contacts

22 endpoints in this group.

Lists contacts from newest to oldest

GET/api/v1/contacts

Scope
read
SDK method
listContacts · list_contacts
MCP tool
listContactsread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidnoOnly this bot's contacts
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "channel": "telegram",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "phone": "905321234567",
      "consent": "opted_in",
      "acquisition_source": "string",
      "attributes": {
        "key": "sehir"
      },
      "last_seen_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 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.

Creates a contact

POST/api/v1/contacts

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.

Scope
contacts:write
SDK method
createContact · create_contact
MCP tool
createContact

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
bot_iduuidyes
external_idstringnolen ≤ 64
namestringnolen ≤ 120
usernamestringnolen ≤ 64
phonestringnolen ≤ 32
tagsstring[]noitems ≤ 20
notesstringnolen ≤ 4000
attributesobjectnoCustom field key → value (text, number, YYYY-MM-DD date or option)

Example request

curl -X POST "https://hiboty.com/api/v1/contacts" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","external_id":"123456789","name":"Jane Smith","tags":["vip"]}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 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.

Returns a single contact (including tags, notes and custom fields)

GET/api/v1/contacts/{id}

Scope
read
SDK method
getContact · get_contact
MCP tool
getContactread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesContact ID

Example request

curl -X GET "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 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.

Updates name, notes, tags and custom fields

PATCH/api/v1/contacts/{id}

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

NameTypeRequiredDescription
idpathuuidyesContact ID

Body fields

NameTypeRequiredDescription
namestring | nullnolen ≤ 120
notesstring | nullnolen ≤ 4000
tagsstring[]noitems ≤ 20
add_tagsstring[]noitems ≤ 20
remove_tagsstring[]noitems ≤ 20
attributesobjectnofields ≤ 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"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "channel": "telegram",
    "external_id": "123456789",
    "name": "Hiboty",
    "username": "ayse",
    "phone": "905321234567",
    "consent": "opted_in",
    "tags": [
      "string"
    ],
    "notes": "string",
    "attributes": {
      "key": "sehir"
    },
    "last_seen_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 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.

Permanently deletes a contact (GDPR)

DELETE/api/v1/contacts/{id}

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.

Scope
contacts:write
SDK method
deleteContact · delete_contact
MCP tool
deleteContactirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesContact ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 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.

Current consent and consent history (newest first, up to 50)

GET/api/v1/contacts/{id}/consent

Contacts opt out by sending STOP and opt back in with START.

Scope
read
SDK method
getContactConsent · get_contact_consent
MCP tool
getContactConsentread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesContact ID

Example request

curl -X GET "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/consent" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consent": "opted_in",
    "source": "string",
    "history": [
      {
        "from": "string",
        "to": "string",
        "source": "string",
        "created_at": "2026-11-06T09:00:00.000Z"
      }
    ]
  }
}

Possible errors

  • 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.

Updates messaging consent (and optional tags)

POST/api/v1/contacts/{id}/consent

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.

Scope
write
SDK method
updateContactConsent · update_contact_consent
MCP tool
updateContactConsentirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesContact ID

Body fields

NameTypeRequiredDescription
consentenumyesopted_in | opted_out
tagsstring[]noitems ≤ 20

Example request

curl -X POST "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/consent" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"consent":"opted_in","tags":["bulten"]}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consent": "opted_in",
    "tags": [
      "string"
    ]
  }
}

Possible errors

  • 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.

Imports contacts from CSV text

POST/api/v1/contacts/import

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.

Scope
contacts:write
SDK method
importContacts · import_contacts
MCP tool
importContacts

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
bot_iduuidyes
csvstringyeslen ≤ 2097152

Example request

curl -X POST "https://hiboty.com/api/v1/contacts/import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","csv":"kanal_kimligi;ad;etiketler\n123456789;Jane Smith;vip"}'

Example response (200)

JSON
{
  "data": {
    "added": 1,
    "updated": 1,
    "skipped": 1,
    "invalid_field_values": 1,
    "errors": [
      {
        "row": 1,
        "code": "missing_channel_id"
      }
    ]
  }
}

Possible errors

  • 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.

Exports contacts as CSV chunks

GET/api/v1/contacts/export

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.

Scope
contacts:read
SDK method
exportContacts · export_contacts
MCP tool
exportContactsread-only

Paginated

Parameters

NameTypeRequiredDescription
consentqueryenumnoConsent statusopted_in | opted_out | unknown
tagquerystringnoContacts with this tag
qquerystringnoSearch in name, username, phone or channel ID
bot_idqueryuuidnoThis bot only
limitqueryintegernoPage size (1–1000, default 1000); 400 if it isn't an integerval 1–1000, default 1000
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/contacts/export?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "csv": "string",
    "row_count": 1,
    "next_cursor": "string"
  }
}

Possible errors

  • 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.

Applies a bulk action to contacts

POST/api/v1/contacts/bulk

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.

Scope
contacts:write
SDK method
bulkContacts · bulk_contacts
MCP tool
bulkContactsirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
operationenumyestag_add | tag_remove | opt_out | delete
idsuuid[]yesitems 1–200
tagstringnoRequired for tag_add and tag_removelen ≤ 32

Example request

curl -X POST "https://hiboty.com/api/v1/contacts/bulk" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"operation":"tag_add","ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"tag":"vip"}'

Example response (200)

JSON
{
  "data": {
    "operation": "string",
    "affected": 1
  }
}

Possible errors

  • 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.

Clears the contact's AI memory

POST/api/v1/contacts/{id}/clear-memory

Older messages aren't summarized again. Any member with access to the contact's bot can do this. Scope: contacts:write.

Scope
contacts:write
SDK method
clearContactMemory · clear_contact_memory
MCP tool
clearContactMemoryirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 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

Example request

curl -X POST "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/clear-memory" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "memory_cleared": true
  }
}

Possible errors

  • 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.

Links the record to another record's customer profile

POST/api/v1/contacts/{id}/profile-link

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.

Scope
contacts:write
SDK method
linkContactProfile · link_contact_profile
MCP tool
linkContactProfile

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
other_contact_iduuidyes

Example request

curl -X POST "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile-link" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"other_contact_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "other_contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Possible errors

  • 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.

Removes the record from its customer profile

DELETE/api/v1/contacts/{id}/profile-link

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.

Scope
contacts:write
SDK method
unlinkContactProfile · unlink_contact_profile
MCP tool
unlinkContactProfileirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile-link" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unlinked": true
  }
}

Possible errors

  • 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.

Lists tags with usage counts

GET/api/v1/contact-tags

Members only see tags on contacts of bots they can access. Most used first. Scope: contacts:read.

Scope
contacts:read
SDK method
listContactTags · list_contact_tags
MCP tool
listContactTagsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/contact-tags?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "key": "sehir",
      "name": "Hiboty",
      "variants": [
        "string"
      ],
      "contact_count": 1,
      "automation_count": 1
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 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.

Renames a tag

POST/api/v1/contact-tags/rename

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.

Scope
contacts:write
SDK method
renameContactTag · rename_contact_tag
MCP tool
renameContactTagirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
tagstringyeslen 1–100
new_namestringyeslen 1–32

Example request

curl -X POST "https://hiboty.com/api/v1/contact-tags/rename" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tag":"vip","new_name":"VIP customer"}'

Example response (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

Possible errors

  • 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.

Merges tags into one

POST/api/v1/contact-tags/merge

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.

Scope
contacts:write
SDK method
mergeContactTags · merge_contact_tags
MCP tool
mergeContactTagsirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
tagsstring[]yesitems 1–50
targetstringyeslen 1–32

Example request

curl -X POST "https://hiboty.com/api/v1/contact-tags/merge" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tags":["vip","premium"],"target":"VIP"}'

Example response (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

Possible errors

  • 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.

Removes tags from all contacts

POST/api/v1/contact-tags/delete

Up to 50 tags at once; contacts aren't deleted. Needs admin permission. Scope: contacts:write.

Scope
contacts:write
SDK method
deleteContactTags · delete_contact_tags
MCP tool
deleteContactTagsirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
tagsstring[]yesitems 1–50

Example request

curl -X POST "https://hiboty.com/api/v1/contact-tags/delete" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"tags":["eski-kampanya"]}'

Example response (200)

JSON
{
  "data": {
    "affected_contacts": 1
  }
}

Possible errors

  • 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.

Lists custom field definitions

GET/api/v1/contact-fields

As in the dashboard, the member role can read them too. Scope: contacts:read.

Scope
contacts:read
SDK method
listContactFields · list_contact_fields
MCP tool
listContactFieldsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/contact-fields?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "key": "sehir",
      "label": "City",
      "type": "metin",
      "options": [
        "string"
      ],
      "ai_writable": true
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 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.

Creates a custom field

POST/api/v1/contact-fields

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.

Scope
contacts:write
SDK method
createContactField · create_contact_field
MCP tool
createContactField

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 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

NameTypeRequiredDescription
keystringyeslen 2–32
labelstringyeslen 1–50
typeenumyesmetin | sayi | tarih | secim
optionsstring[]noitems ≤ 30

Example request

curl -X POST "https://hiboty.com/api/v1/contact-fields" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"key":"sehir","label":"City","type":"secim","options":["Istanbul","Ankara"]}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key": "sehir",
    "label": "City",
    "type": "metin",
    "options": [
      "string"
    ],
    "ai_writable": true
  }
}

Possible errors

  • 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.

Updates a custom field

PATCH/api/v1/contact-fields/{id}

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.

Scope
contacts:write
SDK method
updateContactField · update_contact_field
MCP tool
updateContactFieldirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
labelstringnolen 1–50
optionsstring[]noitems ≤ 30
ai_writablebooleanno

Example request

curl -X PATCH "https://hiboty.com/api/v1/contact-fields/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"City of residence","ai_writable":true}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key": "sehir",
    "label": "City",
    "type": "metin",
    "options": [
      "string"
    ],
    "ai_writable": true,
    "cleared_contacts": 1
  }
}

Possible errors

  • 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.

Deletes a custom field

DELETE/api/v1/contact-fields/{id}

The field's value is removed from every contact irreversibly. Needs admin permission. Scope: contacts:write.

Scope
contacts:write
SDK method
deleteContactField · delete_contact_field
MCP tool
deleteContactFieldirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/contact-fields/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true,
    "cleared_contacts": 1
  }
}

Possible errors

  • 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.