Get started with CSM APIs

The Customer Service Management (CSM) APIs allow you to programmatically manage customers, organizations, products, entitlements, and detail fields. This guide helps you get started with the right API for your use case.

API Categories

Customer APIs

Use these APIs to manage customer accounts and profiles:

• Customer Accounts - Create and manage basic customer accounts
• Customer Profiles - Manage customer profiles including detail fields, organizations, and creating product entitlements
• Customer Detail Fields - Update custom detail field values

When to use:

• Creating customer accounts for help center access
• Syncing customer data from CRM systems
• Updating customer information programmatically

Organization APIs

Use these APIs to manage organizations:

• Organizations - Create and manage organization accounts
• Organization Profiles - Manage organization profiles with detail fields and create product entitlements
• Organization Detail Fields - Update custom detail field values for organizations

When to use:

• Managing companies or groups of customers
• Associating customers with their organizations
• Tracking organization-level information

Product and Entitlement APIs

Use these APIs to manage products and customer entitlements:

• Products - Create and manage products
• Entitlements - Assign products to customers or organizations

When to use:

• Managing product licenses or subscriptions
• Tracking which customers have access to which products
• Implementing tiered support based on product ownership

Choosing Between Profile APIs and Account APIs

Customer Profile APIs vs Customer Account APIs

Recommendation: Use Profile APIs for most integration scenarios. Use Account APIs only when you need simple account creation without additional metadata.

Organization Profile APIs vs Organization APIs

Similar to customers, organization profile APIs provide comprehensive management including detail fields and associations, while basic organization APIs focus on simple account creation.

Bulk vs Individual Operations

When to Use Bulk APIs

Use Bulk APIs when:

• Syncing data from external systems (CRMs, databases)
• Processing multiple records
• Performing regular scheduled syncs
• Need asynchronous processing

Benefits:

• Process up to 100 items per request
• Asynchronous execution (non-blocking)
• Built-in idempotency for safe retries
• Batch error handling

See the Bulk APIs Guide for detailed information and examples.

When to Use singular APIs

Use singular APIs when:

• Creating/updating a single customer or organization
• Responding to real-time user actions
• Building interactive UI features
• Need immediate synchronous responses

Authentication

All CSM APIs use OAuth 2.0 for authentication. You'll need:

1. An Atlassian Cloud account with CSM enabled
2. OAuth 2.0 application credentials (Client ID and Secret)
3. Appropriate scopes for your operations:
   • write:customer:jira-service-management
   • write:customer.profile:jira-service-management
   • write:customer.detail:jira-service-management
   • write:organization:jira-service-management
   • write:organization.profile:jira-service-management
   • write:organization.detail:jira-service-management

See Authentication for detailed setup instructions.

Common Use Cases

Use Case 1: Sync CRM Contacts to CSM

Goal: Keep customer data synchronized between your external CRM and CSM.

Approach:

1. Use Bulk Customer Profile API
2. Schedule regular syncs (hourly or daily)
3. Map CRM fields to CSM detail fields
4. Handle incremental updates

See: HubSpot Integration Guide

Use Case 2: Provision Customers During Onboarding

Goal: Automatically create customer accounts when users sign up.

Approach:

1. Use singular Customer Profile API
2. Create account synchronously during signup flow
3. Associate with relevant organizations and products
4. Set initial detail field values

Use Case 3: Update Support Tier Information

Goal: Update customer support tier based on subscription changes.

Approach:

1. Use Bulk Customer Details API for multiple customers
2. Use individual API for single customer updates
3. Trigger updates on subscription events

Use Case 4: Manage Organization Hierarchies

Goal: Create and maintain organization structures.

Approach:

1. Use Bulk Organization Profile API
2. Create parent organizations first
3. Associate customers with organizations
4. Update organization detail fields

Quick Links

• Full API Reference - API Reference
• Bulk APIs Guide - Bulk operations documentation
• HubSpot Integration - Complete integration example
• Bulk Operations - Async processing details
• Authentication - OAuth 2.0 setup
• Permissions - Required permissions

Need Help?

• Check the API Reference for detailed endpoint documentation
• Review troubleshooting for common issues
• Contact Atlassian Support for additional assistance