Returns all entitlement detail fields, including their configuration. You can use the get entitlement API to get details for a particular entitlement.

Permissions required: Administer Jira global permission.

OAuth 2.0 scopes required:

read:entitlement.detail-field:jira-service-management

Request

This request has no parameters.

Responses

Returns a list of detail fields.

application/json

DetailFieldsWithConfiguration

GET/api/v1/entitlement/details

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/details' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "results": [
    {
      "name": "Region",
      "type": {
        "name": "SELECT",
        "options": [
          "AU",
          "EU",
          "US"
        ]
      },
      "configuration": {
        "position": 1
      }
    }
  ]
}

POST

Create entitlement detail field

Creates an entitlement detail field. You can create up to 50 detail fields.

Permissions required: Administer Jira global permission.

OAuth 2.0 scopes required:

write:entitlement.detail-field:jira-service-management

Request

Request bodyapplication/json

name

string

Required

type

DetailFieldType

Required

Responses

Returns the created detail field.

application/json

CreateDetailFieldResponse

POST/api/v1/entitlement/details

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/details' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Region",
  "type": {
    "name": "SELECT",
    "options": [
      "AU",
      "EU",
      "US"
    ]
  }
}'

200Response

{
  "name": "Region",
  "type": {
    "name": "SELECT",
    "options": [
      "AU",
      "EU",
      "US"
    ]
  }
}

PUT

Edit entitlement detail field

Renames an entitlement detail field and/or changes the available options for SELECT or MULTISELECT fields.

Permissions required: Administer Jira global permission.

OAuth 2.0 scopes required:

write:entitlement.detail-field:jira-service-management

Request

Path parameters

fieldName

string

Required

Request bodyapplication/json

name

string

Required

options

array<string>

Responses

Returns the edited entitlement detail field.

application/json

EditDetailFieldResponse

PUT/api/v1/entitlement/details/{fieldName}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/details/{fieldName}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Region",
  "options": [
    "AU",
    "EU",
    "US"
  ]
}'

200Response

{
  "name": "Region",
  "type": {
    "name": "SELECT",
    "options": [
      "AU",
      "EU",
      "US"
    ]
  }
}

DEL

Delete entitlement detail field

Deletes an entitlement detail field and all values stored for it for all entitlements. You cannot restore a detail field once it has been deleted.

Permissions required: Administer Jira global permission.

OAuth 2.0 scopes required:

delete:entitlement.detail-field:jira-service-management

Request

Path parameters

fieldName

string

Required

Responses

Returns no response if the entitlement detail field is deleted.

DEL/api/v1/entitlement/details/{fieldName}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/details/{fieldName}' \
  --header 'Authorization: Bearer <access_token>'

GET

Get entitlement

Returns an entitlement, including its details. You can get entitlements for a customer using the get customer entitlements API, and get entitlements for an organization using the get organization entitlements API.

Permissions required: Jira Service Management agent.

OAuth 2.0 scopes required:

read:entitlement:jira-service-management

read:entitlement.detail:jira-service-management

Request

Path parameters

entitlementId

string

Required

Responses

Returns the requested entitlement.

application/json

Entitlement

GET/api/v1/entitlement/{entitlementId}

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/{entitlementId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "id": "3858a61a-d337-42e6-993e-e13e1c366d4f",
  "product": {
    "id": "3858a61a-d337-42e6-993e-e13e1c366d4f",
    "name": "Acme Widget"
  },
  "entitledEntity": {
    "id": "123",
    "type": "CUSTOMER"
  },
  "details": [
    {
      "id": "321",
      "name": "Region",
      "type": {
        "name": "SELECT",
        "options": [
          "AU",
          "EU",
          "US"
        ]
      },
      "values": [
        "EU"
      ],
      "configuration": {
        "position": 1
      }
    }
  ]
}

DEL

Delete entitlement

Deletes the specified entitlement along with its detail fields. You cannot restore an entitlement once it has been deleted.

Permissions required: Administer Jira global permission.

OAuth 2.0 scopes required:

delete:entitlement:jira-service-management

Request

Path parameters

entitlementId

string

Required

Responses

Returns no response if the entitlement is deleted.

DEL/api/v1/entitlement/{entitlementId}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/{entitlementId}' \
  --header 'Authorization: Bearer <access_token>'

PUT

Set entitlement detail

Permissions required: Jira Service Management agent.

OAuth 2.0 scopes required:

write:entitlement.detail:jira-service-management

Request

Path parameters

entitlementId

string

Required

Query parameters

fieldName

string

Required

Request bodyapplication/json

values

array<string>

Responses

Returns the updated field.

application/json

UpdateDetailFieldResponse

PUT/api/v1/entitlement/{entitlementId}/details

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlement/{entitlementId}/details?fieldName=Tier' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "values": [
    "EU"
  ]
}'

200Response

{
  "id": "321",
  "name": "Region",
  "type": {
    "name": "SELECT",
    "options": [
      "AU",
      "EU",
      "US"
    ]
  },
  "values": [
    "EU"
  ]
}

GET

Get entitlementsExperimental

Returns a paginated list of the customer or organization's entitlements, along with their details. Returns a max of 50 results.

Permissions required: Jira Service Management agent.

OAuth 2.0 scopes required:

read:organization:entitlement:jira-service-management

read:customer:entitlement:jira-service-management

Request

Query parameters

entityType

EntitlementEntityType

Required

entityId

string

Required

start

integer

limit

integer

productId

string

Header parameters

X-ExperimentalApi

ExperimentalHeader

Required

Responses

Returns a paginated list of entitlements.

application/json

PaginatedEntitlements

GET/api/v1/entitlements

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/jsm/csm/cloudid/{cloudId}/api/v1/entitlements?entityType=ORGANIZATION&entityId=qm%3A9edf598a-85d4-4db9-bf2e-7245922b4ea8%3A0000e9d8-a22e-4220-ac63-412ff9eec053' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'X-ExperimentalApi: opt-in'

200Response

{
  "startAt": 0,
  "maxResults": 25,
  "total": 200,
  "isLast": false,
  "results": [
    {
      "id": "3858a61a-d337-42e6-993e-e13e1c366d4f",
      "product": {
        "id": "3858a61a-d337-42e6-993e-e13e1c366d4f",
        "name": "Acme Widget"
      },
      "entitledEntity": {
        "id": "123",
        "type": "CUSTOMER"
      },
      "details": [
        {
          "id": "321",
          "name": "Region",
          "type": {
            "name": "SELECT"
          },
          "values": [
            "EU"
          ],
          "configuration": {}
        }
      ]
    }
  ]
}