Integrating a Contact Centre or External System

The Customer Service Management (CSM) request intake APIs allow you to create requests from contact-centre interactions and enrich them with transcripts, agent notes, and follow-up detail.

Customer service agents work primarily in their external system (for example, a telephony platform, IVR, voice bot, CRM, or contact-centre suite) and the following APIs are designed for integration scenarios where requests need to be escalated to CSM for further follow up.

Overview

Request intake APIs provide synchronous operations for:

• Request creation: Create a CSM request from an external interaction such as a call, callback, or bot session
• Case enrichment: Add call transcripts, agent notes, and structured follow-up detail as comments
• Customer association: Attach the end customer to the request as the reporter by email address
• Channel classification: Record the channel an interaction arrived on, such as voice or messaging

All request intake operations are synchronous. A successful request returns the created issue identifiers immediately, so there is no task to poll.

The external intake endpoint uses the default form configured for the Customer Experience. Client-supplied form selection is not part of this integration model.

Available Request Intake APIs

Request Operations

1. POST /api/v1/request/form/external - Create a Request from an External System

Creates a request in CSM from an external interaction, using the default form configured for the Customer Experience. Optionally associates the end customer with the request through their email address, and records the channel the interaction arrived on.

Use Case: Open a case automatically when a call, IVR selection, or bot session needs tracking and follow-up in CSM.

Form used: Default form for the Customer Experience

Returns: 200 OK with the created issue identifiers

2. POST /api/v1/request/form/helpcenter/{helpCenterId}/issue/{issueIdOrKey}/comment - Add a Comment to a Request

Adds a comment to a request that has already been created. Use this API to attach content that arrived too late for the original creation call, and to control whether that content is visible to the customer.

Use Case: Append a call transcript, agent wrap-up notes, or a post-call analysis summary to a case after the interaction ends.

Visibility: Internal by default, or customer-visible when explicitly set

Returns: 200 OK with the created comment

Key Concepts

Base URL

All request intake calls use the following base URL, with the Cloud ID of the target site:

1
2
https://api.atlassian.com/jsm/csm/cloudid/{cloudId}

Authentication

Third-party integrations must authenticate with an Atlassian service account using OAuth 2.0 client credentials (2LO). This is the supported method. Do not build against user session authentication or a personal account's credentials.

Create an Atlassian service account for the integration. The service account must have the Customer Service Management User role, and its credentials must:

• Use the OAuth 2.0 authentication type
• Have the write:csm-request:jira-service-management scope associated with them

Exchange the client credentials for a bearer token, then send that token on every request. There is no audience or scope parameter in this exchange; scopes come from the service account configuration.

Identifiers

Creator and Reporter Behaviour

These roles are intentionally separate in the external intake model:

• Issue creator: The authenticated caller, which is the service account used by the integration
• Issue reporter: The customer identified by reporterEmail, when provided. CSM creates or retrieves the customer account
• No reporter email: The issue is still created, but no separate customer reporter is attached through this field

Intake Channels

Use intakeChannel to classify where an interaction came from. Send VOICE for telephony and contact-centre integrations. If omitted, the value defaults to EXTERNAL for backward compatibility.

Accepted values are EMAIL, AI_AGENT, SUPPORT_SITE, EXTERNAL, EMBED, VOICE, SMS, SDK, and MESSAGING. The sub-channels EMBED_CHAT, SUPPORT_SITE_CHAT, and WHATSAPP are also accepted.

Basic Usage Example

Step 1: Request an Access Token

Exchange the service account's client credentials for a bearer token:

1
2
curl -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

Step 2: Create the Request

1
2
curl -X POST https://api.atlassian.com/jsm/csm/cloudid/YOUR_CLOUD_ID/api/v1/request/form/external \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "helpCenterId": "YOUR_CUSTOMER_EXPERIENCE_ID",
    "origin": "Salesforce Service Cloud",
    "summary": "Customer requested help with account access",
    "description": "Customer contacted the support line after failing multi-factor authentication. Agent verified identity and opened a case for follow-up.",
    "reporterEmail": "customer@example.com",
    "intakeChannel": "VOICE",
    "metadata": {
      "agentId": "agent-314",
      "contactId": "contact-8291",
      "queue": "priority-support"
    }
  }'

Response:

1
2
{
  "id": "10021",
  "key": "CSM-1",
  "helpCenterId": "YOUR_CUSTOMER_EXPERIENCE_ID",
  "link": "https://example.atlassian.net/helpcenter/12345/user/requests/CSM-1"
}

Step 3: Add the Transcript as a Comment

Use the key returned in step 2. The comment body is Atlassian Document Format (ADF). Comments are internal unless public is set to true.

1
2
curl -X POST https://api.atlassian.com/jsm/csm/cloudid/YOUR_CLOUD_ID/api/v1/request/form/helpcenter/YOUR_CUSTOMER_EXPERIENCE_ID/issue/YOUR_ISSUE_KEY/comment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "public": false,
    "body": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Call transcript summary: customer could not access the portal after password reset. Identity verified. Escalated to account administration."
            }
          ]
        }
      ]
    }
  }'

Common Use Cases

1. Create a Case from a Call or IVR Selection

Open a case when an interaction needs tracking beyond the call itself.

1. Capture the caller's identity, queue, and reason for contact in your telephony platform
2. Call the external intake API with intakeChannel set to VOICE
3. Store the returned issue key against the interaction record in your platform

2. Enrich a Case with Post-Call Content

Keep the creation call small and add detail once the interaction completes.

1. Create the request at the start of the interaction with a concise summary
2. Wait for the transcript or recording analysis to complete
3. Add the transcript as an internal comment using the stored issue key

3. Escalate from a Bot to a Human Agent

Hand off an automated session that could not resolve the customer's problem.

1. Create the request when the bot determines escalation is required
2. Set reporterEmail so the case is attached to the customer
3. Add the bot session transcript as a comment so the agent has full context

4. Integrate a CRM-Originated Interaction

Create CSM cases from interactions that begin in your CRM.

1. Trigger on the CRM event that represents a new interaction
2. Map CRM fields to summary, description, and flat metadata values
3. Use a consistent origin value so CSM traffic from this system is identifiable

Best Practices

1. Payload Design

• Send a concise summary and reserve long transcript content for comments
• Keep metadata flat, minimal, and operationally useful
• Use a consistent origin value for each external system
• Set intakeChannel explicitly rather than relying on the default

2. Error Handling

• Validate email format and metadata structure before sending
• Treat 400 and 403 as configuration or data problems, not transient faults
• Retry 5xx responses carefully, with exponential backoff
• Capture the x-trace-id response header on every non-2xx response and log it with your own correlation ID

3. Correlation and Duplicate Prevention

• Store the returned issue key in your external platform for future updates
• Record a "created" flag against the source-system record before retrying
• There is no idempotency key on these APIs, so a retry after a timeout can create a duplicate request

4. Authentication and Credentials

• Use a dedicated service account for each integration rather than sharing one
• Store client credentials in a secrets manager and grant least-privilege access to them
• Do not commit credentials or access tokens to source control, and do not write them to logs
• Request a fresh access token when the current one expires, and handle 401 by re-authenticating

5. Comment Visibility

• Set visibility intentionally on every comment
• Default to internal for raw transcripts and agent notes
• Use customer-visible comments only for content written for the customer

6. Monitoring and Logging

• Log the issue key and your own correlation ID for every created request
• Track creation success and failure rates by origin
• Set up alerts for sustained failure rates and for authentication failures

Troubleshooting

Issue: 500 with error key barista.form.processing.validation.error

Solution: No default form is configured for the Customer Experience. This is a configuration issue rather than a temporary fault, so the request will keep failing until a default form is in place. Confirm the default form, then retry. Match on this error key to handle the case specifically rather than treating it as a transient error.

Issue: 403 Forbidden on every request

Solution:

• Confirm the service account has the Customer Service Management User role
• Confirm the credentials carry the write:csm-request:jira-service-management scope

Issue: 400 Bad Request when setting a customer

Solution: Validate reporterEmail before sending. Invalid email values cause the request to be rejected. If the customer's email is unavailable, omit the field; the request is still created without a customer reporter.

Issue: 400 Bad Request when sending metadata

Solution: Only primitive JSON values are supported in metadata. Flatten nested objects and arrays into individual keys before sending.

Issue: Duplicate requests created for one interaction

Solution: A retry after a timeout creates a second request, because these APIs have no idempotency key. Record a "created" flag and the returned issue key against the source-system record, and check it before retrying.

Issue: Requests are created but no customer is attached

Solution: The customer is attached through reporterEmail only. The service account is always the creator, and this is expected behaviour. Supply reporterEmail if the case should be associated with the end customer.

Related Documentation

• CSM REST API reference - Full endpoint reference
• API Quick Start - Overview of CSM APIs
• Use Amazon Connect with Customer Service Management - A working contact-centre integration built on these APIs

Need Help?

For support with request intake APIs:

• Review the API documentation
• Check the error key and message in the response body for the specific failure
• Contact Atlassian Support with the x-trace-id from the failing response and a sample payload