Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED US2-FED

Create ServiceNow tickets for security findings

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/security/findings/servicenow_ticketshttps://api.ap2.datadoghq.com/api/v2/security/findings/servicenow_ticketshttps://api.datadoghq.eu/api/v2/security/findings/servicenow_ticketshttps://api.ddog-gov.com/api/v2/security/findings/servicenow_ticketshttps://api.us2.ddog-gov.com/api/v2/security/findings/servicenow_ticketshttps://api.datadoghq.com/api/v2/security/findings/servicenow_ticketshttps://api.us3.datadoghq.com/api/v2/security/findings/servicenow_ticketshttps://api.us5.datadoghq.com/api/v2/security/findings/servicenow_tickets

Overview

Create ServiceNow tickets for security findings. This operation creates a case in Datadog and a ServiceNow ticket linked to that case for bidirectional sync between Datadog and ServiceNow. You can create up to 50 ServiceNow tickets per request and associate up to 50 security findings per ServiceNow ticket. Security findings that are already attached to another ServiceNow ticket will be detached from their previous ServiceNow ticket and attached to the newly created ServiceNow ticket. This endpoint requires any of the following permissions:

  • security_monitoring_findings_write
  • appsec_vm_write

    • Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    Array of ServiceNow ticket creation request data objects.

    attributes

    object

    Attributes of the ServiceNow ticket to create.

    assignee_id

    string

    Unique identifier of the Datadog user assigned to the case backing the ServiceNow ticket.

    description

    string

    Description of the ServiceNow ticket. If not provided, the description will be automatically generated.

    priority

    enum

    Datadog case priority mapped to the ServiceNow ticket priority. If not provided, the priority will be automatically set to "NOT_DEFINED". Allowed enum values: NOT_DEFINED,P1,P2,P3,P4,P5

    default: NOT_DEFINED

    title

    string

    Title of the ServiceNow ticket. If not provided, the title will be automatically generated.

    relationships [required]

    object

    Relationships of the ServiceNow ticket to create.

    findings [required]

    object

    Security findings to create a ServiceNow ticket for.

    data

    [object]

    Array of security finding data objects.

    id [required]

    string

    Unique identifier of the security finding.

    type [required]

    enum

    Security findings resource type. Allowed enum values: findings

    default: findings

    project [required]

    object

    Case management project configured with the ServiceNow integration. It is used to create the ServiceNow ticket.

    data [required]

    object

    Data object representing a case management project.

    id [required]

    string

    Unique identifier of the case management project.

    type [required]

    enum

    Projects resource type. Allowed enum values: projects

    default: projects

    type [required]

    enum

    ServiceNow tickets resource type. Allowed enum values: servicenow_tickets

    default: servicenow_tickets

    {
  "data": [
    {
      "attributes": {
        "assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
        "description": "A description of the ServiceNow ticket.",
        "priority": "P4",
        "title": "A title for the ServiceNow ticket."
      },
      "relationships": {
        "findings": {
          "data": [
            {
              "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
              "type": "findings"
            }
          ]
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "servicenow_tickets"
    }
  ]
}

    Response

    Created

    List of case responses.

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    Array of case response data objects.

    attributes

    object

    Attributes of the case.

    archived_at

    date-time

    Timestamp of when the case was archived.

    assigned_to

    object

    User assigned to the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    attributes

    object

    Custom attributes associated with the case as key-value pairs where values are string arrays.

    <any-key>

    [string]

    closed_at

    date-time

    Timestamp of when the case was closed.

    created_at

    date-time

    Timestamp of when the case was created.

    creation_source

    string

    Source of the case creation.

    description

    string

    Description of the case.

    due_date

    string

    Due date of the case.

    insights

    [object]

    Insights of the case.

    ref

    string

    Reference of the insight.

    resource_id

    string

    Unique identifier of the resource. For example, the unique identifier of a security finding.

    type

    string

    Type of the resource. For example, the type of a security finding is "SECURITY_FINDING".

    jira_issue

    object

    Jira issue associated with the case.

    error_message

    string

    Error message if the Jira issue creation failed.

    result

    object

    Result of the Jira issue creation.

    account_id

    string

    Account ID of the Jira issue.

    issue_id

    string

    Unique identifier of the Jira issue.

    issue_key

    string

    Key of the Jira issue.

    issue_url

    string

    URL of the Jira issue.

    status

    string

    Status of the Jira issue creation. Can be "COMPLETED" if the Jira issue was created successfully, or "FAILED" if the Jira issue creation failed.

    key

    string

    Key of the case.

    modified_at

    date-time

    Timestamp of when the case was last modified.

    priority

    string

    Priority of the case.

    servicenow_ticket

    object

    ServiceNow ticket associated with the case.

    result

    object

    Result of the ServiceNow ticket creation or attachment.

    instance_name

    string

    ServiceNow instance name extracted from the ticket URL.

    sys_id

    string

    Unique identifier of the ServiceNow incident record.

    sys_target_link

    string

    Direct link to the ServiceNow incident record.

    sys_target_sys_id

    string

    Unique identifier of the target ServiceNow record.

    table_name

    string

    ServiceNow table containing the incident record.

    url

    string

    URL of the ServiceNow incident record.

    status

    string

    Status of the ServiceNow ticket operation. Can be "COMPLETED" if successful, or "FAILED" if the operation failed.

    status

    string

    Status of the case.

    status_group

    string

    Status group of the case.

    status_name

    string

    Status name of the case.

    title

    string

    Title of the case.

    type

    string

    Type of the case. For security cases, this is always "SECURITY".

    id

    string

    Unique identifier of the case.

    relationships

    object

    Relationships of the case.

    created_by

    object

    User who created the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    modified_by

    object

    User who last modified the case.

    data [required]

    object

    Relationship to user object.

    id [required]

    string

    A unique identifier that represents the user.

    type [required]

    enum

    Users resource type. Allowed enum values: users

    default: users

    project

    object

    Project in which the case was created.

    data [required]

    object

    Data object representing a case management project.

    id [required]

    string

    Unique identifier of the case management project.

    type [required]

    enum

    Projects resource type. Allowed enum values: projects

    default: projects

    type [required]

    enum

    Cases resource type. Allowed enum values: cases

    default: cases

    {
  "data": [
    {
      "attributes": {
        "archived_at": "2025-01-01T00:00:00.000Z",
        "assigned_to": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "attributes": {
          "<any-key>": []
        },
        "closed_at": "2025-01-01T00:00:00.000Z",
        "created_at": "2025-01-01T00:00:00.000Z",
        "creation_source": "CS_SECURITY_FINDING",
        "description": "A description of the case.",
        "due_date": "2025-01-01",
        "insights": [
          {
            "ref": "/security/appsec/vm/library/vulnerability/dfa027f7c037b2f77159adc027fecb56?detection=static",
            "resource_id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
            "type": "SECURITY_FINDING"
          }
        ],
        "jira_issue": {
          "error_message": "{\"errorMessages\":[\"An error occured.\"],\"errors\":{}}",
          "result": {
            "account_id": "463a8631-680e-455c-bfd3-3ed04d326eb7",
            "issue_id": "2871276",
            "issue_key": "PROJ-123",
            "issue_url": "https://domain.atlassian.net/browse/PROJ-123"
          },
          "status": "COMPLETED"
        },
        "key": "PROJ-123",
        "modified_at": "2025-01-01T00:00:00.000Z",
        "priority": "P4",
        "servicenow_ticket": {
          "result": {
            "instance_name": "example",
            "sys_id": "abcdef0123456789abcdef0123456789",
            "sys_target_link": "https://example.service-now.com/incident.do?sys_id=abcdef0123456789abcdef0123456789",
            "sys_target_sys_id": "abcdef0123456789abcdef0123456789",
            "table_name": "incident",
            "url": "https://example.service-now.com/now/nav/ui/classic/params/target/incident.do?sys_id=abcdef0123456789abcdef0123456789"
          },
          "status": "COMPLETED"
        },
        "status": "OPEN",
        "status_group": "SG_OPEN",
        "status_name": "Open",
        "title": "A title for the case.",
        "type": "SECURITY"
      },
      "id": "c1234567-89ab-cdef-0123-456789abcdef",
      "relationships": {
        "created_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "modified_by": {
          "data": {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "users"
          }
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "cases"
    }
  ]
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      ## default
# 

    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security/findings/servicenow_tickets" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": [
    {
      "attributes": {
        "assignee_id": "f315bdaf-9ee7-4808-a9c1-99c15bf0f4d0",
        "description": "A description of the ServiceNow ticket.",
        "priority": "NOT_DEFINED",
        "title": "A title for the ServiceNow ticket."
      },
      "relationships": {
        "findings": {
          "data": [
            {
              "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
              "type": "findings"
            }
          ]
        },
        "project": {
          "data": {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "projects"
          }
        }
      },
      "type": "servicenow_tickets"
    }
  ]
}
EOF