In Zendesk, users are individual people who create tickets or interact with your support team. In Customer Service Management, these become customers. CSM customers can also belong to multiple organizations.

Zendesk Organizations → Customer Service Management Organizations

Zendesk organizations group users together by business. Customer Service Management organizations work the same way.

Custom fields → Detail fields

Zendesk custom fields store additional information as key-value pairs. CSM detail fields serve the same purpose with different characteristics:

Typed fields (TEXT, SELECT, BOOLEAN, etc.)
Predefined options for SELECT and MULTISELECT fields
Validation rules based on field type

New to Customer Service Management? Start with the getting started guide.

Map your data types

Both Zendesk users and organizations have custom fields. These map to Customer Service Management detail fields like this:

Zendesk field type	CSM field type	Example use	Notes
Drop-down	`SELECT`	Region, tier, status	Define all options during field creation, prior to importing data.
Multi-select	`MULTISELECT`	Skills, interests, tags	Maintains multiple values per field. Define all options during field creation, prior to importing data.
Text	`TEXT`	Names, short descriptions
Multi-line	`TEXT`	Long descriptions, comments	CSM TEXT fields handle both single and multi-line text.
Checkbox	`BOOLEAN`	Premium customer, VIP status	Maps to true/false values.
Numeric	`NUMBER`	Employee count, ticket IDs	Integer values only in Zendesk. CSM NUMBER type supports both integers and decimals.
Decimal	`NUMBER`	Revenue, ratings, percentages	Direct mapping for decimal numbers
Date	`DATE`	Contract start, renewal date	Both stored in YYYY-MM-DD format.
Regex	`TEXT`	Phone numbers, zip codes, SSNs	CSM doesn't support direct regex validation - please use equivalent field type e.g. `PHONE`, `URL`.

Integration steps

1. Prepare your data and setup CSM

Export from Zendesk

Export users, organizations, and their custom fields
Clean up duplicates and missing data

Create detail fields in Customer Service Management

Before importing data, set up your detail fields to match your Zendesk custom fields. You can learn about how to do this in the documentation on managing customer detail fields. You can also use the following APIs:

Customer detail fields: Use the create customer detail field API.

For organization detail fields: Use the create organization detail field API.

Important considerations:

Plan your field types - CSM detail fields use specific types and can't be changed after creation
Set up validation options - For SELECT and MULTISELECT fields, define all possible values before beginning to migrate data

2. Use bulk APIs

Import customers Use the Bulk customer profile management API to create customers with details.

1
2
{
  "customers": [
    {
      "operationType": "CREATE",
      "payload": {
        "email": "john.doe@example.com",
        "displayName": "John Doe",
        "details": [
          {"name": "Region", "values": ["North America"]},
          {"name": "Tier", "values": ["Enterprise"]}
        ],
        "associateOrganizations": [123]
      }
    },
    {
      "operationType": "CREATE",
      "payload": {
        "email": "jane.smith@example.com",
        "displayName": "Jane Smith",
        "details": [
          {"name": "Region", "values": ["Europe"]},
          {"name": "Tier", "values": ["Premium"]}
        ],
        "associateOrganizations": [456]
      }
    },
    {
      "operationType": "CREATE",
      "payload": {
        "email": "bob.wilson@acme.com",
        "displayName": "Bob Wilson",
        "details": [
          {"name": "Region", "values": ["Asia Pacific"]},
          {"name": "Tier", "values": ["Basic"]}
        ],
        "associateOrganizations": [123, 789]
      }
    }
  ]
}

Import organizations Use the Bulk organization profile management API to create organizations with details and associated customers.

1
2
{
  "organizations": [
    {
      "operationType": "CREATE",
      "payload": {
        "name": "Acme Corporation",
        "details": [
          {"name": "Industry", "values": ["Technology"]},
          {"name": "Company Size", "values": ["Large"]},
          {"name": "Annual Revenue", "values": ["10000000"]}
        ]
      }
    },
    {
      "operationType": "CREATE",
      "payload": {
        "name": "Global Solutions Inc",
        "details": [
          {"name": "Industry", "values": ["Finance"]},
          {"name": "Company Size", "values": ["Medium"]},
          {"name": "Annual Revenue", "values": ["5000000"]}
        ]
      }
    },
    {
      "operationType": "CREATE",
      "payload": {
        "name": "Startup Innovations",
        "details": [
          {"name": "Industry", "values": ["Technology"]},
          {"name": "Company Size", "values": ["Small"]},
          {"name": "Annual Revenue", "values": ["500000"]}
        ]
      }
    }
  ]
}

Additional bulk operations:

Bulk customer account management - Bulk create customer accounts (without adding detail field values)
Bulk customer detail field management - Bulk manage customer detail field values (without creating customers)
Bulk organization management - Bulk manage organizations (without adding detail field values)
Bulk organization detail field management - Bulk manage organization detail field values (without creating organizations)

Monitor bulk operations: All bulk API calls return a taskId. Check the status of the bulk operation with the GET task status API

Common issues

Authentication errors

Check your API token permissions
Verify workspace ID in requests

Learn how to authenticate with Customer Service Management APIs and manage API tokens.

Data validation failures

Ensure detail field names match exactly (case-sensitive)
Check SELECT field values match predefined options

Rate limiting

Add delays between requests
Use bulk APIs instead of individual calls

Script implementation example

1
2
import requests

def import_customers_batch(customers):
    """Migrate customers using bulk API"""
    url = "https://your-domain.atlassian.net/gateway/api/jsm/csm/v1/customer/profile/bulk"
    headers = {
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        "X-ExperimentalApi": "opt-in",
        "Idempotency-Key": uuid.uuid4(),
    }

    payload = {
        "customers": [{
            "operationType": "CREATE",
            "payload": customer
        } for customer in customers]
    }

    response = requests.post(url, headers=headers, json=payload)
    return response.json().get("taskId")

# Transform Zendesk data
customers = []
for zendesk_contact in zendesk_data:
    # Safely access nested custom fields to avoid KeyError when missing
    region = zendesk_contact.get("custom_fields", {}).get("region")
    customer = {
        "email": zendesk_contact["email"],
        "displayName": zendesk_contact["name"],
    }
    customer["details"] = [{"name": "Region", "values": [region]}] if region else []
    customers.append(customer)

# Import in batches of 50
for i in range(0, len(customers), 50):
    batch = customers[i:i+50]
    task_id = migrate_customers_batch(batch)
    # Monitor task_id for completion

Additional resources:

Need help? Contact Atlassian support.