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. A successful request returns 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: 1000 detail-field operations total, counted across all customers in the request

4. POST /api/v1/customer/details/definitions/bulk - Create Customer Detail Field Definitions

Creates customer detail-field definitions (the schema, not values) in bulk. This is a setup-time operation that provisions new custom fields on the customer entity, ready to receive values via the value-update bulk endpoints above.

Use Case: During initial tenant onboarding or when integrating with a new external system, provision the full set of custom fields (Tier, Account Manager, Region, Renewal Date, etc.) in a single call before importing customer data.

This endpoint is create-only. It does not modify or replace existing detail-field definitions. See Unique field names below for the full contract.

Max per Request: 50 detail field definitions

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: 1000 detail-field operations total, counted across all organizations in the request

4. POST /api/v1/organization/details/definitions/bulk - Create Organization Detail Field Definitions

Creates organization detail-field definitions (the schema, not values) in bulk. This is a setup-time operation that provisions new custom fields on the organization entity, ready to receive values via the value-update bulk endpoints above.

Use Case: During initial tenant onboarding or when integrating with a new external system, provision the full set of organization custom fields (Region, Account Manager, Customer Tier, Renewal Date, etc.) in a single call before importing organization data.

This endpoint is create-only. It does not modify or replace existing detail-field definitions. See Unique field names below for the full contract.

Max per Request: 50 detail field definitions

Key Concepts

Asynchronous Processing

When you submit a bulk operation:

The API returns immediately with an id and statusUrl
The operation processes in the background
You poll the status endpoint to check progress
Results are available for up to 3 days
Asynchronous tasks are not guaranteed to run in order

Example response:

1
2
{
  "id": "abc123def456",
  "statusUrl": "/api/v1/tasks/abc123def456"
}

Task Limits

Each tenant (cloud site, identified by cloudId) can have up to 5 non-terminal bulk tasks queued or in progress at the same time. Tasks with NOT_STARTED or IN_PROGRESS status count toward this limit. Tasks with FINISHED or FAILED status do not.

If the task limit is reached, new bulk requests are rejected with 400 Bad Request and the message Maximum number of tasks reached. Wait for existing tasks to finish before submitting more work. Non-terminal tasks older than 30 minutes are treated as timed out during task-limit checks, which frees capacity for new tasks.

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

Unique field names

The detail-field definition endpoints are create-only. Every name in the request must be unique:

Within the request itself: comparison is case-insensitive and trimmed ("Region", "region", and " region " all collide).
Against existing detail fields for the same entity type: if any requested name matches a detail field that already exists on the customer or organization entity, the entire request is rejected.

If either rule is violated, the call is rejected synchronously with 400 Bad Request (with the colliding names listed in the response body) and no task is created. Nothing is partially applied. To update an existing detail field's shape, delete it and re-create it via this API.

The total number of customer and organization detail fields is also capped (currently 50 per entity type). If the size of the request exceeds the remaining budget, the call is rejected with 400 Bad Request.

Task Status Monitoring

Poll the task status endpoint to check results:

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

Status values:

NOT_STARTED: Task is queued
IN_PROGRESS: Task is running
FINISHED: Task finished. Check failures to distinguish complete success from partial success
FAILED: Task failed or timed out before completion

Example completed response:

1
2
{
  "id": "abc123def456",
  "type": "BULK_CUSTOMER_PROFILE_CREATE_UPDATE",
  "status": "FINISHED",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-15T10:01:23Z",
  "failures": [
    {
      "entity": "CUSTOMER",
      "entityId": "invalid@example",
      "operation": "UPSERT",
      "operatedOn": "CUSTOMER_ACCOUNT",
      "error": "Invalid customer email"
    }
  ]
}

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 '{
    "customerProfiles": [
      {
        "operationType": "UPSERT",
        "payload": {
          "email": "john.doe@example.com",
          "displayName": "John Doe",
          "details": [
            {
              "name": "Phone",
              "values": ["+1-555-0123"]
            },
            {
              "name": "Company",
              "values": ["Acme Corp"]
            }
          ]
        }
      },
      {
        "operationType": "UPSERT",
        "payload": {
          "email": "jane.smith@example.com",
          "displayName": "Jane Smith",
          "details": [
            {
              "name": "Phone",
              "values": ["+1-555-0124"]
            },
            {
              "name": "Company",
              "values": ["Tech Inc"]
            }
          ]
        }
      }
    ]
  }'

# Response:
# {
#   "id": "abc123def456",
#   "statusUrl": "/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": [
    {
      "customerId": "qm:82a83bc1-d19a-4220-b388-af3f7d92165d:a495e659-5978-402f-a878-636e415ba1c1",
      "operations": [
        {
          "operationType": "UPDATE",
          "payload": {
            "name": "Support Tier",
            "values": ["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 and organization account/profile APIs
Use up to 1000 total detail-field operations per request for customer and organization detail-field value APIs
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 only
Log failures for manual review
Use a new idempotency key when retrying a changed request body

3. Task and Rate Limiting

Keep no more than 5 tasks queued or in progress for a tenant (cloudId)
Don't submit dependent batches until prerequisite tasks complete
Implement exponential backoff for retries
Respect API rate limits separately from the task limit 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 detail field names 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 names are correct
Verify entities exist for update operations

Issue: "Maximum number of tasks reached"

Solution:

Poll existing task IDs and wait for tasks to reach FINISHED or FAILED
Reduce the number of concurrent batch submissions
Submit dependent work only after prerequisite tasks finish

Issue: Task stuck in IN_PROGRESS

Solution:

Wait longer. Large batches can take several minutes
If stuck for more than 30 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