VX Agents

API directory · Customer Support

Zendesk Users & Organizations

v1.0.0 · 17 endpoints · 0 connections · shared by vx.ai

For support teams that keep their Zendesk customer directory tidy: find end users by email or external id, upsert them with create_or_update, group them into organizations with domain names and tags, and see every user, membership and open-ticket count for an account before you reply.

Connect this API to an AI agent Browse all specs

What you can do with Zendesk Users & Organizations via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /api/v2/users/search searchUsers Find users by email, name, phone or external id
GET /api/v2/users/{user_id} getUser Get one user's profile, role, tags and organization
PUT /api/v2/users/{user_id} updateUser Update a user's name, phone, tags, notes, organization or custom fields
GET /api/v2/users/{user_id}/related getUserRelated Count a user's requested, assigned and CC'd tickets
POST /api/v2/users/create_or_update createOrUpdateUser Create a user, or update the one with the same email or external id
GET /api/v2/users/{user_id}/organizations listUserOrganizations List the organizations a user belongs to
PUT /api/v2/users/{user_id}/organizations/{organization_id}/make_default setDefaultOrganization Make one of a user's organizations their default
GET /api/v2/organizations listOrganizations List organizations in the account
POST /api/v2/organizations createOrganization Create an organization
GET /api/v2/organizations/search searchOrganizations Find an organization by exact name or external id
GET /api/v2/organizations/autocomplete autocompleteOrganizations Find organizations whose name starts with some text
GET /api/v2/organizations/{organization_id} getOrganization Get one organization with its domains, tags and fields
PUT /api/v2/organizations/{organization_id} updateOrganization Update an organization's name, domains, tags, notes or fields
GET /api/v2/organizations/{organization_id}/related getOrganizationRelated Count an organization's tickets and users
GET /api/v2/organizations/{organization_id}/users listOrganizationUsers List the users in an organization
GET /api/v2/organizations/{organization_id}/organization_memberships listOrganizationMemberships List an organization's memberships (which users belong to it)
POST /api/v2/organization_memberships createOrganizationMembership Add a user to an organization

Authentication

zendesk_api_token

HTTP Basic

Zendesk API token over HTTP Basic: username [email protected]/token, password = the API token. (An OAuth access token with the users:read users:write organizations:read organizations:write scopes also works as a Bearer token.)

How to get a credential

  1. Sign in as a Zendesk admin and open Admin Center > Apps and integrations > APIs > Zendesk API.
  2. Turn on Token access and click Add API token; name it (e.g. VX Agents directory).
  3. Copy the token (it is shown once).
  4. Use the email of the agent the token should act as, followed by /token, as the username and the token as the password.

Permissions used

Role needed Operations
Agent searchUsers, getUser, getUserRelated, listUserOrganizations, listOrganizations, searchOrganizations, autocompleteOrganizations, getOrganization, getOrganizationRelated, listOrganizationUsers, listOrganizationMemberships
Agent allowed to manage end users createOrUpdateUser, updateUser, createOrganizationMembership, setDefaultOrganization
Admin (or agent with org management rights) createOrganization, updateOrganization

API tokens act as the user in the username, so that user's role decides access.

Common errors

Status Meaning Fix
401 Wrong email/token pair, or token access is off Check the username ends in /token and token access is enabled in Admin Center.
403 The user's role cannot edit users or organizations Use an admin's email or give the agent role user/org management rights.
422 Validation failed (duplicate email, organization name taken) Search first and update the existing record.
429 Rate limit (per minute, by plan) Wait for the Retry-After seconds and retry.

Store it as a VX Agents credential (Basic auth: username email/token, password = API token).

Usage guide

Setup

  • Credential: HTTP Basic with username [email protected]/token and a Zendesk API token as the password (Admin Center > Apps and integrations > APIs > Zendesk API).
  • Set the server variable subdomain to your account (for https://acme.zendesk.com use acme).
  • Worth pinning as presets: the organization ids you work with most, and your custom user/organization field keys.

Keep a customer record up to date

  1. Find the person: searchUsers with query=email:[email protected] (or name:"Jane Doe", phone:...), or external_id=<your CRM id>.
  2. getUser for role, tags, notes and user_fields; getUserRelated for how many tickets they requested, are assigned or CC'd on.
  3. New or changed person: createOrUpdateUser with {"user": {"name": "...", "email": "...", "external_id": "...", "organization_id": 123}}. It matches on email or external_id, so it will not create duplicates. Use updateUser to change fields on a known id.
  4. listUserOrganizations to see every organization the user belongs to; setDefaultOrganization picks the one new tickets go to.

Work with organizations

  1. Find it: searchOrganizations with name (exact) or external_id, or autocompleteOrganizations with name=<first letters>.
  2. getOrganization for domain_names, tags, notes, group_id and organization_fields; getOrganizationRelated for ticket and user counts.
  3. listOrganizationUsers or listOrganizationMemberships to see who belongs to it.
  4. createOrganization with {"organization": {"name": "Acme", "domain_names": ["acme.com"]}}; updateOrganization to change it. Users whose email matches domain_names join automatically.
  5. Add someone by hand: createOrganizationMembership with {"organization_membership": {"user_id": 1, "organization_id": 2}}.

Good to know

  • Confirm with the user before any create or update: these change customer data that agents and triggers rely on.
  • tags on updateUser / updateOrganization replaces the whole list: read the current tags and send the full list.
  • Organization names must be unique (422 on a duplicate). Users can belong to several organizations only when the account allows multiple memberships.
  • Lists return 100 per page; follow next_page. Times are ISO 8601 UTC.
  • No deletes, merges or suspensions by design.

Source: Zendesk Support API reference (https://developer.zendesk.com/api-reference/ticketing/users/users/), checked 2026-10-24.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Zendesk Users & Organizations” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs