4.1 Case Retrieval and Polling

Customers must poll to retrieve case updates, as Expereo does not have subscriptions (a future improvement).

• Single Case Retrieval: The cases resolver allows retrieval of a single case using the id parameter. When retrieving a case via ID, you receive all related communications and updates (the complete history).
• Multiple Cases: You cannot query for multiple Case IDs in a single query.
• Time Filtering: The RetrieveUpdatedCases query uses the lastModifiedMinutes parameter to narrow the response to updates within that period. If this parameter is skipped, the default value is 0, which results in all case data (updates for all cases from all services) being returned. If no updates occur within the specified interval, the update record list will be empty.

Example Query: RetrieveUpdatedCases

query RetrieveUpdatedCases {
  viewer {
    account {
      cases(id: "CASE_ID", serviceId: "SERVICE_ID", lastModifiedMinutes: 1440, customerReference: "CUSTOMER_REFERENCE") {
        id
        subject
        createdDate
        customerReference
        lastModifiedDate # Used by customers to manage update retrieval
        origin
        startOfIncident
        communications {
          message
          type
          timestamp
          sentBy
        }
        site {
          siteId
        }
        service {
          serviceId
        }
        status
        type
      }
    }
  }
}

4.2 Creating a New Case (Mutation)

The createCase mutation requires mandatory fields: subject*, type*, serviceId*, and message*.

Critical Requirement for Incident Case Creation: If the Type is set to Incident, you must pass both startOfIncident and endOfIncident in ISO 8601 format to resolve the known creation issue.

• startOfIncident is the date the incident was first reported.
• endOfIncident can be passed as null, the same value as startOfIncident, or a far future date. Attempts to pass None in certain implementations (e.g., Python) or omitting the field result in generic errors like {"message":"An error has occurred"} or the code HC0011.

Example Mutation: CreateCase

mutation CreateCase(
    $subject: String!
    $type: String!
    $startOfIncident: String
    $customerReference: String
    $serviceId: String!
    $message: String!
    $sentBy: String
) {
    createCase(
        subject: $subject
        type: $type
        startOfIncident: $startOfIncident
        customerReference: $customerReference
        serviceId: $serviceId
        message: $message
        sentBy: $sentBy
    ) {
        id
    }
}

4.3 Replying to and Referencing Cases

• Reply to Case: Uses the replyToCase mutation, requiring id* (Case ID) and message*.

mutation ReplyToCase($caseId: String!, $message: String!, $sentBy: String) {
    replyToCase(caseId: $caseId, message: $message, sentBy: $sentBy)
}

• Add Customer Reference: Uses the addCustomerReference mutation to link an existing case to your internal system reference ID.

mutation AddCustomerReference($caseId: String!, $customerReference: String!) {
    addCustomerReference(caseId: $caseId, customerReference: $customerReference)
}