Skip to content

Manage case links

This page complements the Cases GraphQL API guide. Use it for the link operations that support the case workflow.

To create a case or manage its lifecycle first, see Manage the case lifecycle.

Create, update, and delete links to external systems (ServiceNow, 4Me, etc.) or internal resources on a case.

What this covers

This guide shows how to create, update, and delete links on a case. Use links for related records in external systems or internal resources.

Prerequisites

  • Create a service principal and get a bearer token. See the Cases GraphQL quickstart.
  • Get the full case ID before you create a link.
  • Have the target URL and any external reference value ready.

Workflow

Managing links with the Cases GraphQL API consists of the following steps:

  1. Create a link with the case ID and target URL.
  2. Update only the fields that changed.
  3. Delete the link when the target is no longer relevant.
mutation createCaseLink($input: CreateCaseLinkInput!) {
    createCaseLink(input: $input) {
        id
        caseId
        url
        title
        type
        isInternal
        createdAt
    }
}

Variables

{
    "input": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "url": "https://company.service-now.com/nav_to.do?uri=/incident.do?sys_id=123abc",
        "reference": "INC0123456",
        "title": "ServiceNow Incident",
        "type": "ServiceNow",
        "isInternal": false
    }
}

Response example

{
    "data": {
        "createCaseLink": {
            "id": "550e8400-e29b-41d4-a716-446655440400",
            "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "url": "https://company.service-now.com/nav_to.do?uri=/incident.do?sys_id=123abc",
            "title": "ServiceNow Incident",
            "type": "ServiceNow",
            "isInternal": false,
            "createdAt": "2024-08-14T16:00:00Z"
        }
    }
}

Save the returned id for later updates or deletion.

Updates are partial (PATCH semantics) — only provided fields are modified.

mutation updateCaseLink($input: UpdateCaseLinkInput!) {
    updateCaseLink(input: $input) {
        id
        caseId
        url
        title
        type
        isInternal
        updatedAt
    }
}

Variables

{
    "input": {
        "id": "550e8400-e29b-41d4-a716-446655440400",
        "title": "ServiceNow Incident (Resolved)",
        "reference": "INC0123456"
    }
}

Response example

{
    "data": {
        "updateCaseLink": {
            "id": "550e8400-e29b-41d4-a716-446655440400",
            "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "url": "https://company.service-now.com/nav_to.do?uri=/incident.do?sys_id=123abc",
            "title": "ServiceNow Incident (Resolved)",
            "type": "ServiceNow",
            "isInternal": false,
            "updatedAt": "2024-08-14T16:15:00Z"
        }
    }
}

mutation deleteCaseLink($input: DeleteCaseLinkInput!) {
    deleteCaseLink(input: $input) {
        id
        caseId
        url
    }
}

Variables

{
    "input": {
        "id": "550e8400-e29b-41d4-a716-446655440400"
    }
}

Response example

{
    "data": {
        "deleteCaseLink": {
            "id": "550e8400-e29b-41d4-a716-446655440400",
            "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "url": "https://company.service-now.com/nav_to.do?uri=/incident.do?sys_id=123abc"
        }
    }
}

Error handling

Check the HTTP status and the GraphQL response body. A request can return HTTP 200 with an errors array.

Common failures include an invalid link ID, a case ID from another tenant, and a URL that the caller can't use. Check the returned error before you retry.

Constraints and considerations

  • Links can reference external systems (ServiceNow, 4Me, etc.) or internal resources.
  • reference is an optional identifier for the linked resource.
  • Links with isInternal set to true are only visible to internal users. The default is false, and only partner or MDR provider users can set it to true.
  • Retrieve a case's existing links via the links field on the case query.
  • deleteCaseLink is a hard delete. Data isn't recoverable.