--- title: "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." method: POST path: "/applicationInstruct/setInstruct" --- # 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 - Base URL: `http://localhost:8098/ichallenge` - URL: `http://localhost:8098/ichallenge/applicationInstruct/setInstruct` - Auth: none declared ## Request body - InstructMessage: ### Message instructing Home Office about an event, or action to perform. #### Mandatory items for all messages messageHeader, messageType, hoReference, and consumerReference #### Optional items note #### Message Types and Mandatory Elements APPEAL_REQUESTED: [none] REQUEST_CHALLENGE_END: endReason, endChallengeDate REQUEST_EVIDENCE_BUNDLE: challenge, deadlineDate REQUEST_REVIEW: deadlineDate (a review has its own deadline) HEARING: hearing HEARING_BUNDLE_READY: hearing (passing just hmctsHearingRef and hearingType) COURT_OUTCOME: courtOutcome PERMISSION_TO_APPEAL: courtType DEFAULT: No additional mandatory elements; generic item that is not a bundle/review request - `messageHeader` MessageHeader, required: Message parameters (not business oriented). - `eventDateTime` string, date-time, required: UTC timestamp for debugging purposes - `correlationId` string, required: ID allowing correlation between service consumer and API log files. Expected to be unique, for example, a UUID - `consumer` Consumer, required: Consumer of the service. - `code` 'HMCTS', required: Short code for the consumer - `description` string: Description of the consumer (for legibility reasons) - `messageType` 'APPEAL_REQUESTED' | 'REQUEST_CHALLENGE_END' | 'REQUEST_EVIDENCE_BUNDLE' | 'REQUEST_REVIEW' | 'HEARING' | 'HEARING_BUNDLE_READY' | 'COURT_OUTCOME' | 'PERMISSION_TO_APPEAL' | 'DEFAULT', required: Message type - `hoReference` string, required: Home Office reference (UAN or CID case ID) - `consumerReference` ConsumerRef, required: Consumer reference; reference provided to Home Office, to be used in subsequent calls to update the same item. - `consumer` Consumer, required: Consumer of the service. - `code` 'HMCTS', required: Short code for the consumer - `description` string: Description of the consumer (for legibility reasons) - `code` 'HMCTS_CHALLENGE_REF', required: Short code for the reference - `description` string - `value` string, required: Value for the reference - `endReason` 'STRUCK_OUT' | 'ABANDONED' | 'WITHDRAWN' | 'NOT_VALID' | 'INCORRECT_DETAILS': Code indicating reason for ending a challenge. *Mandatory if messageType is REQUEST_CHALLENGE_END* - `endChallengeDate` string, 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* - `deadlineDate` string: 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* - `challenge` Challenge: Details of a challenge (initially, all appeal related). - `appealType` 'PROTECTION' | 'REVOCATION_OF_PROTECTION' | 'DEPRIVATION_OF_CITIZENSHIP' | 'HUMAN_RIGHTS' | 'EEA', required: The type of appeal - `appealTierType` 'FIRST_TIER', required: The type of appeal tier - `challengeSubmissionDate` string, required: Date (and time, if available) of challenge submission, 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 - `applicants` Person[], required: List of applicants (will initially be just one) - `givenName` string: Person's given names. Assumed to be a concatenated list of names - `familyName` string: Person's family names. Assumed to be a concatenated list of names - `fullName` string: Person's full name - `gender` PersonGender - `code` string: Letter code for the gender - `description` string: Gender description - `dayOfBirth` integer: Day of month the person was born on, from 1-31. No leading zeroes - `monthOfBirth` integer: Month of year (Gregorian calendar) the person was born in, from 1-12. No leading zeroes - `yearOfBirth` integer: Year the person was born in (4 digits) - `nationality` PersonNationality: Person's nationality - `code` string: Short code for the nationality - `description` string: Description of the nationality - `hearing` Hearing: Details of a hearing. - `hmctsHearingRef` string, required: HMCTS reference for a hearing. (Allows for multiple hearings though usually it's just one.) - `hearingLocation` string: Venue where the hearing is to take place - `hearingDate` string, date: Date of the hearing, in the standard format yyyy-mm-dd - `hearingTime` string: Time of the hearing, in the standard format HH:mm:ss. Time is assumed to be in UTC - `hearingType` 'PAPER' | 'ORAL', required: Type of hearing - `witnessQty` integer: Number of witnesses to be called to provide evidence at the hearing - `witnessNames` string: Names of witnesses. Recorded as notes in HMCTS, so cannot be a list of names - `courtOutcome` CourtOutcome: Court type and outcome of the appeal. - `courtType` 'FIRST_TIER' | 'FTPA' | 'UTPA', required: Court (tribunal) type - `outcome` 'ALLOWED' | 'DISMISSED' | 'GRANTED' | 'REFUSED' | 'REHEARD' | 'REMADE', required: Appeal outcome - `note` string: Optional note. Can be used for indicating notification type and, possibly, Home Office actions required ## Response `200` OK - InstructResponse: Response round-tripping request message header. - `messageHeader` MessageHeader: Message parameters (not business oriented). - `eventDateTime` string, date-time, required: UTC timestamp for debugging purposes - `correlationId` string, required: ID allowing correlation between service consumer and API log files. Expected to be unique, for example, a UUID - `consumer` Consumer, required: Consumer of the service. - `code` 'HMCTS', required: Short code for the consumer - `description` string: Description of the consumer (for legibility reasons) ## Other responses - `400`: Invalid status value ## Changes - **2026-06-29** `227b8cd41bd6`: 1 info - added the new `APPEAL_REQUESTED` enum value to the request property `messageType` - **2026-03-26** `294294b97455`: 1 breaking, 1 info - added the pattern `^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)$` to the request property `challenge/challengeSubmissionDate` - the `challenge/challengeSubmissionDate` request property format was generalized from `date-time` to no format - **2026-03-26** `9750f2217ddd`: 1 breaking, 1 info - added the pattern `^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)$` to the request property `deadlineDate` - the `deadlineDate` request property format was generalized from `date-time` to no format - **2026-03-26** `3389bb785ab9`: 1 info - endpoint added [Operation history](https://skmtc.dev/hm-courts-and-tribunals-service/apis/appeals-interface/changes/applicationInstruct/setInstruct/post.md) --- [API](https://skmtc.dev/hm-courts-and-tribunals-service/apis/appeals-interface.md) - [All operations](https://skmtc.dev/hm-courts-and-tribunals-service/apis/appeals-interface/llms.txt) - [OpenAPI document](https://skmtc.dev/hm-courts-and-tribunals-service/apis/appeals-interface/revisions/0b0977ebe459?raw)