The Customer Service Management (CSM) bulk APIs allow you to create, update, and manage large volumes of customer and organization data. These APIs are designed for integration scenarios where you need to sync data from external systems like CRMs, support platforms, or customer databases.

Overview

Bulk APIs provide asynchronous operations for:

Customer management: Create and update customer accounts and profiles in bulk
Organization management: Manage organizations and their associations
Detail field updates: Update custom detail field values across multiple entities
Relationship management: Associate customers with organizations and products

All bulk operations are asynchronous, returning a task ID that you can poll to check the status and results of the operation.

Available Bulk APIs

Customer Bulk Operations

1. POST /api/v1/customer/bulk - Create or Update Customer Accounts

Creates or updates basic customer account records. Use this API when you need to quickly create customer accounts with just essential information (email and display name). This is ideal for initial bulk imports or when you want to create accounts first and populate detail fields later.

Use Case: Rapidly onboard customers from your CRM with minimal information, then enrich their profiles later with additional detail fields.

Max per Request: 50 customers

2. POST /api/v1/customer/profile/bulk - Manage Customer Profiles

Creates or updates comprehensive customer profiles including detail field values and organization associations. This is the most feature-rich customer bulk operation, allowing you to populate the complete customer profile in a single request.

Use Case: Complete customer migration from external systems where you want to import customer data, custom fields, and organizational relationships all at once.

Max per Request: 100 customers

3. POST /api/v1/customer/details/bulk - Update Customer Detail Fields

Updates specific detail field values for existing customers without modifying other profile attributes. Use this API when you need to update custom fields across many customers.

Use Case: Sync updated customer attributes (e.g., support tier, health score) from your CRM to CSM without re-importing entire customer profiles.

Max per Request: 100 customers

Organization Bulk Operations

1. POST /api/v1/organization/bulk - Create or Update Organizations

Creates or updates basic organization records. Similar to customer accounts, this operation handles essential organization information (name, ID) without detail fields.

Use Case: Quickly set up organization structures in CSM for grouping customers and managing organizational relationships.

Max per Request: 50 organizations

2. POST /api/v1/organization/profile/bulk - Manage Organization Profiles

Creates or updates comprehensive organization profiles including detail field values. This allows you to populate complete organization information in bulk.

Use Case: Migrate organizational hierarchies and company data from your CRM with all associated custom fields and attributes.

Max per Request: 100 organizations

3. POST /api/v1/organization/details/bulk - Update Organization Detail Fields

Updates specific detail field values for existing organizations. Use this API to sync organization-level custom fields.

Use Case: Update organization attributes (e.g., industry, contract status, renewal date) across multiple organizations without re-importing entire profiles.

Max per Request: 100 organizations

Key Concepts

Asynchronous Processing

When you submit a bulk operation:

The API returns immediately with a taskId and statusUrl
The operation processes in the background
You poll the status endpoint to check progress
Results are available for up to 3 days

Example response:

1
2
{
  "taskId": "abc123def456",
  "statusUrl": "https://api.atlassian.com/api/v1/tasks/abc123def456"
}

Idempotency Keys

Every bulk API request requires an Idempotency-Key header. This ensures safe retries without duplicating operations.

This key identifies each distinct request so different operations should use a different Idempotency-Key value.
Should be a UUID (e.g., f47ac10b-58cc-4372-a567-0e02b2c3d479)
Reusing the same key with the same request body returns the same task ID
Reusing the same key with a different request body results in an error

Task Status Monitoring

Poll the task status endpoint to check results:

1
2
GET /api/v1/tasks/{taskId}

Status values:

PROCESSING: Task is running
COMPLETED: Task finished successfully (may include partial failures)
FAILED: Task failed completely

Example completed response:

1
2
{
  "taskId": "abc123def456",
  "status": "COMPLETED",
  "createdDate": "2026-01-15T10:00:00Z",
  "completedDate": "2026-01-15T10:01:23Z",
  "failures": [
    {
      "index": 1,
      "message": "Customer with email 'invalid@' is not valid"
    }
  ]
}

Basic Usage Example

Here's a complete example of creating customer profiles in bulk:

1
2
# Step 1: Submit bulk operation
curl -X POST https://api.atlassian.com/api/v1/customer/profile/bulk \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-ExperimentalApi: true" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "email": "john.doe@example.com",
        "displayName": "John Doe",
        "details": {
          "phone": "+1-555-0123",
          "company": "Acme Corp"
        }
      },
      {
        "email": "jane.smith@example.com",
        "displayName": "Jane Smith",
        "details": {
          "phone": "+1-555-0124",
          "company": "Tech Inc"
        }
      }
    ]
  }'

# Response:
# {
#   "taskId": "abc123def456",
#   "statusUrl": "https://api.atlassian.com/api/v1/tasks/abc123def456"
# }

# Step 2: Poll for results
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.atlassian.com/api/v1/tasks/abc123def456

Common Use Cases

Syncing from an external CRM System

Use bulk APIs to sync customer data from your external CRM:

Export customer data from your CRM
Transform data to CSM format
Submit in batches using bulk profile API
Monitor task status and handle failures
Schedule regular syncs (e.g., hourly or daily)

See HubSpot Integration Guide for a detailed example.

Updating Detail Fields

Update specific detail field values without modifying other profile information:

1
2
POST /api/v1/customer/details/bulk
{
  "customers": [
    {
      "email": "john.doe@example.com",
      "details": [
        {
          "fieldId": "support-tier",
          "operation": "UPDATE",
          "value": "Premium"
        }
      ]
    }
  ]
}

Creating Organizations

Bulk create organizations before associating customers:

1
2
POST /api/v1/organization/profile/bulk
{
  "organizations": [
    {
      "name": "Acme Corporation",
      "details": {
        "industry": "Manufacturing",
        "website": "https://acme.example.com"
      }
    }
  ]
}

Best Practices

1. Batch Size Optimization

Use 50-100 records per request for customer profiles
Start with smaller batches (10-20) when testing
Monitor performance and adjust batch size accordingly

2. Error Handling

Always check the task status for failures
Implement retry logic for failed records
Log failures for manual review
Don't retry the entire batch—only failed records

3. Rate Limiting

Don't submit new batches until previous tasks complete
Implement exponential backoff for retries
Respect API rate limits to avoid throttling

4. Data Validation

Validate data before submission:

Ensure email formats are valid
Check required fields are present
Deduplicate records within each batch
Verify field IDs exist in your CSM instance

5. Monitoring and Logging

Log all task IDs and idempotency keys
Track success and failure rates
Set up alerts for high failure rates
Monitor sync job duration and performance

Troubleshooting

Issue: "Idempotency key already used"

Solution: Generate a new UUID for each distinct request. Only reuse keys when retrying the exact same request.

Issue: High failure rate

Solution:

Check task status response for specific error messages
Validate data format (especially emails)
Ensure detail field IDs are correct
Verify entities exist for update operations

Issue: Task stuck in PROCESSING

Solution:

Wait longer—large batches can take several minutes
If stuck for >10 minutes, contact Atlassian support with the task ID

Issue: "Customer not found" errors

Solution:

Use UPSERT operations when unsure if customer exists
Ensure email or customerId is correct
Create customers before updating detail fields

API Quick Start - Overview of CSM APIs
Bulk Operations - Detailed bulk operation concepts
HubSpot Integration Guide - Complete integration example
CSV Import - Alternative for large-scale imports

Need Help?

For support with bulk APIs:

Review the API documentation
Check the task status for detailed error messages
Contact Atlassian Support with your task IDs and sample payloads