How to create organizations using the Zendesk API: A complete guide

Organizations are one of Zendesk's most powerful features for managing customer relationships at scale. They let you group users together, route tickets automatically, and control visibility of support conversations. While you can create organizations manually through the Zendesk interface, the real power comes from automating this process through the Zendesk API.

Whether you're migrating from another platform, syncing with your CRM, or building a self-service signup flow, knowing how to create organizations via the Zendesk Organizations API is essential for any serious implementation. This guide walks you through everything you need to know, from authentication to handling edge cases. If you're looking to automate organization management beyond basic API calls, eesel AI can handle the entire workflow for you.

What you'll need to get started

Before diving into code, make sure you've got these prerequisites in place:

• A Zendesk account with admin access. Only admins and agents with custom roles can create organizations via API.
• An API token. You'll need to generate this from your Zendesk Admin Center under Apps and integrations > APIs > Zendesk API.
• Your Zendesk subdomain. This is the first part of your Zendesk URL (e.g., yourcompany in yourcompany.zendesk.com).
• A tool to make HTTP requests. We'll show examples using cURL, Python, and JavaScript, so pick what works for your stack.

The Zendesk API uses basic authentication with an email address and API token combination. This is more secure than using your password and lets you control access granularly.

Step 1: Generate your Zendesk API token

Your API token is the key that lets your code authenticate with Zendesk. Here's how to create one:

1. Log into your Zendesk account as an admin
2. Click the Admin Center icon in the sidebar
3. Navigate to Apps and integrations > APIs > Zendesk API
4. Click the Settings tab
5. Enable Token Access if it isn't already on
6. Click the plus (+) icon to add a new token
7. Give it a descriptive name like "Organization Management API"
8. Copy the token immediately (Zendesk only shows it once)

Store this token securely. Treat it like a password. Anyone with your token can access your Zendesk data through the API.

Pro tip: Create separate tokens for different integrations rather than reusing one everywhere. This makes it easier to revoke access if needed without breaking other systems.

Step 2: Understand the organizations endpoint

The Organizations API follows REST conventions. To create an organization, you'll make a POST request to:

https://{subdomain}.zendesk.com/api/v2/organizations

The request body is a JSON object containing the organization properties. Here's what a minimal create request looks like:

{
  "organization": {
    "name": "Acme Corporation"
  }
}

The only required field is name, and it must be unique across your Zendesk account. You can't include pipe characters (|) in the name, or the request will fail.

Beyond the basics, you can set several useful properties:

Authentication uses HTTP Basic Auth. Combine your email address with /token: and your API token, then base64 encode the result. The header looks like this:

Authorization: Basic {base64_encoded_credentials}

Step 3: Create your first organization

Let's put this into practice with working code examples. Each example creates an organization with common fields you'd actually use.

Using cURL

SUBDOMAIN="yourcompany"
EMAIL="admin@yourcompany.com"
TOKEN="your_api_token_here"

curl -X POST "https://${SUBDOMAIN}.zendesk.com/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -d '{
    "organization": {
      "name": "Acme Corporation",
      "domain_names": ["acme.com", "acmecorp.com"],
      "external_id": "CRM-12345",
      "tags": ["enterprise", "priority"],
      "details": "Enterprise customer since 2020"
    }
  }'

Using Python

import requests
import base64

subdomain = "yourcompany"
email = "admin@yourcompany.com"
token = "your_api_token_here"

credentials = base64.b64encode(
    f"{email}/token:{token}".encode()
).decode()

organization = {
    "organization": {
        "name": "Acme Corporation",
        "domain_names": ["acme.com", "acmecorp.com"],
        "external_id": "CRM-12345",
        "tags": ["enterprise", "priority"],
        "details": "Enterprise customer since 2020"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/organizations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {credentials}"
    },
    json=organization
)

if response.status_code == 201:
    created_org = response.json()["organization"]
    print(f"Created organization ID: {created_org['id']}")
    print(f"Name: {created_org['name']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Using JavaScript/Node.js

const axios = require('axios');

// Configuration
const config = {
  subdomain: 'yourcompany',
  email: 'admin@yourcompany.com',
  token: 'your_api_token_here'
};

// Organization data
const organization = {
  organization: {
    name: 'Acme Corporation',
    domain_names: ['acme.com', 'acmecorp.com'],
    external_id: 'CRM-12345',
    tags: ['enterprise', 'priority'],
    details: 'Enterprise customer since 2020'
  }
};

// Make the request
axios.post(
  `https://${config.subdomain}.zendesk.com/api/v2/organizations`,
  organization,
  {
    headers: {
      'Content-Type': 'application/json'
    },
    auth: {
      username: `${config.email}/token`,
      password: config.token
    }
  }
)
.then(response => {
  const org = response.data.organization;
  console.log(`Created organization ID: ${org.id}`);
  console.log(`Name: ${org.name}`);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

A successful creation returns HTTP 201 with the complete organization object, including the auto-generated id field you'll need for future updates.

Step 4: Work with custom organization fields

Most Zendesk implementations use custom fields to store additional organization data like account tiers, regions, or CRM IDs. Here's how to work with them via API.

First, you need to know what custom fields exist. You can find them in your Zendesk Admin Center under Objects and rules > Organizations > Fields, or retrieve them via API:

curl "https://{subdomain}.zendesk.com/api/v2/organization_fields" \
  -u "{email}/token:{token}"

Each custom field has a unique key (like account_tier or region). When you're creating or updating an organization, include these in the organization_fields object:

{
  "organization": {
    "name": "Acme Corporation",
    "organization_fields": {
      "account_tier": "enterprise",
      "region": "north_america",
      "crm_id": "CRM-12345",
      "contract_value": 50000
    }
  }
}

The value format depends on the field type:

• Text fields: String values
• Dropdown fields: The option tag value (not the display name)
• Numeric fields: Numbers (not strings)
• Date fields: ISO 8601 format (2024-01-15)
• Checkbox fields: Boolean (true or false)

Common use case: Syncing organization data from your CRM. Set up a webhook or scheduled job that pushes updates to Zendesk whenever account details change in your primary system. This keeps support agents working with current information.

Step 5: Handle errors and edge cases

Production code needs to handle things going wrong. Here are the most common errors you'll encounter:

401 Unauthorized

This means your credentials are invalid. Check that:

• Your API token is correct and hasn't been revoked
• Your email address matches the account that owns the token
• You're using the right format: email/token:token (note the /token: part)

422 Unprocessable Entity

The request was understood but couldn't be processed. Common causes:

• Duplicate name: Organization names must be unique. Check existing organizations first.
• Invalid characters: Names can't contain pipe characters (|).
• Missing required fields: The name field is mandatory.
• Invalid custom field values: Make sure dropdown values match the defined options exactly.

429 Too Many Requests

You've hit Zendesk's rate limit. The Organizations API allows 700 requests per minute. If you need to create organizations in bulk, add delays between requests:

import time

for org_data in organizations:
    response = requests.post(url, json=org_data, auth=auth)
    if response.status_code == 429:
        # Wait and retry
        time.sleep(1)
        response = requests.post(url, json=org_data, auth=auth)
    # Process response...
    time.sleep(0.1)  # Be nice to the API

Best practice: When building integrations, always check response status codes and implement exponential backoff for 429 errors. Log failed requests so you can retry them later.

Automating organization management with eesel AI

Managing organizations manually doesn't scale. As your customer base grows, keeping Zendesk organizations in sync with your CRM, billing system, and other tools becomes a significant operational burden.

This is where we can help. At eesel AI, we've built an AI teammate that integrates directly with Zendesk and can automate organization-based workflows.

Here's how our customers use eesel AI with organizations:

• Automatic organization assignment: When a ticket comes in, our AI can look up the requester in your CRM, create or update their organization in Zendesk, and route the ticket to the right team based on organization properties.
• Smart escalation: We can read organization custom fields (like account tier or SLA level) and escalate tickets from enterprise customers automatically.
• Organization-aware responses: Our AI drafts replies that reference organization-specific details like contract terms, dedicated account managers, or previous issues.

Unlike building custom API integrations, eesel AI learns from your existing data and workflows. You describe what you want in plain English (like "If the organization tier is enterprise, CC the account manager"), and our AI handles the API calls, error handling, and logic.

You can start with our AI Copilot drafting replies for agent review, then level up to full automation as you build confidence. Most teams see payback within two months.

Start building with the Zendesk organizations API

You now have everything you need to create and manage organizations programmatically in Zendesk. Let's recap the key steps:

1. Generate an API token from your Zendesk Admin Center
2. Structure your POST request to /api/v2/organizations with the organization data
3. Handle the JSON response to get the created organization's ID
4. Use custom fields to store organization-specific data
5. Implement proper error handling for production code

The Organizations API is just the beginning. You can also update organizations, merge duplicates, manage organization memberships, and set up organization-based business rules.

For advanced use cases like bulk imports or bi-directional sync with other systems, consider whether an AI-powered solution might save your team time. Try eesel AI free for 7 days and see how automation can transform your support operations.