Sign in

v10

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-06-2943243.8 KB

Instructs Home Office downstream systems. Note: Use of the term 'instruct' avoids any confusion with existing business terms, such as 'notification' and 'direction', which are not overly descriptive to the Home Office.

post/applicationInstruct/setInstruct

Request body

messageType'APPEAL_REQUESTED' | 'REQUEST_CHALLENGE_END' | 'REQUEST_EVIDENCE_BUNDLE' | 'REQUEST_REVIEW' | 'HEARING' | 'HEARING_BUNDLE_READY' | 'COURT_OUTCOME' | 'PERMISSION_TO_APPEAL' | 'DEFAULT' required

Message type

hoReferencestring required

Home Office reference (UAN or CID case ID)

endReason'STRUCK_OUT' | 'ABANDONED' | 'WITHDRAWN' | 'NOT_VALID' | 'INCORRECT_DETAILS'

Code indicating reason for ending a challenge. Mandatory if messageType is REQUEST_CHALLENGE_END

endChallengeDatestring date-time

Date (and time, if available) the challenge was ended, in the standard format yyyy-mm-dd (with HH:mm:ss if the time is available, otherwise not). Date/time is assumed to be in UTC. Mandatory if messageType is REQUEST_CHALLENGE_END

deadlineDatestring

Deadline date (and time, if available) for the appeal, in the standard format yyyy-mm-dd (with HH:mm:ss if the time is available, otherwise not). Date/time is assumed to be in UTC

courtType'FIRST_TIER' | 'UPPER_TRIBUNAL' | 'COURT_OF_APPEAL' | 'SUPREME_COURT'

Court type. Mandatory if messageType is PERMISSION_TO_APPEAL

notestring

Optional note. Can be used for indicating notification type and, possibly, Home Office actions required

Example request

{
  "endChallengeDate": "2017-07-21T17:32:28Z",
  "courtType": "FIRST_TIER",
  "note": "Additional notes from HMCTS",
  "messageHeader": {
    "eventDateTime": "2017-07-21T17:32:28Z",
    "correlationId": "ABC2344BCED2234EA",
    "consumer": {
      "code": "HMCTS",
      "description": "HM Courts and Tribunal Service"
    }
  },
  "messageType": "REQUEST_CHALLENGE_END",
  "courtOutcome": {
    "courtType": "FIRST_TIER",
    "outcome": "DISMISSED"
  },
  "endReason": "STRUCK_OUT",
  "deadlineDate": "2017-07-21T17:32:28Z",
  "challenge": {
    "appealTierType": "FIRST_TIER",
    "appealType": "DEPRIVATION_OF_CITIZENSHIP",
    "applicants": [
      {
        "gender": {
          "code": "M (denoting male)",
          "description": "Male"
        },
        "nationality": {
          "code": "CAN (denoting Canada)",
          "description": "Canada"
        },
        "dayOfBirth": 21,
        "givenName": "Capability",
        "familyName": "Smith",
        "fullName": "Capability Smith",
        "monthOfBirth": 0,
        "yearOfBirth": 1970
      },
      {
        "gender": {
          "code": "M (denoting male)",
          "description": "Male"
        },
        "nationality": {
          "code": "CAN (denoting Canada)",
          "description": "Canada"
        },
        "dayOfBirth": 21,
        "givenName": "Capability",
        "familyName": "Smith",
        "fullName": "Capability Smith",
        "monthOfBirth": 0,
        "yearOfBirth": 1970
      }
    ],
    "challengeSubmissionDate": "2017-07-21T17:32:28Z"
  },
  "hearing": {
    "hearingType": "ORAL",
    "witnessQty": 6,
    "witnessNames": "John Smyth, Jennie Walker",
    "hearingDate": "2017-07-21",
    "hearingLocation": "Royal Courts of Justice, London",
    "hearingTime": "10:30:00Z",
    "hmctsHearingRef": "hmctsHearingRef"
  },
  "hoReference": "nnnn-nnnn-nnnn-nnnn (UAN) or CID (case ID, e.g. 001234567)",
  "consumerReference": {
    "code": "HMCTS_CHALLENGE_REF",
    "description": "HMCTS challenge reference",
    "value": "xxxyyyynnn-nnn",
    "consumer": {
      "code": "HMCTS",
      "description": "HM Courts and Tribunal Service"
    }
  }
}

Response

OK

Example response

{
  "messageHeader": {
    "eventDateTime": "2017-07-21T17:32:28Z",
    "correlationId": "ABC2344BCED2234EA",
    "consumer": {
      "code": "HMCTS",
      "description": "HM Courts and Tribunal Service"
    }
  }
}