NOMIS API Documentation

API Endpoint

https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Version: 1.22.0

FORMAT: 1A HOST: https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Offender ¶

Get details ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1417AE

RequestsSuccessfulUnknown offenderInvalid NOMS ID

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "given_name": "JENIFER",
  "middle_names": "ESMERALADA JANE",
  "surname": "HALLIBUT",
  "date_of_birth": "1970-01-01",
  "aliases": [
    {
      "given_name": "JILLY",
      "surname": "HALLS",
      "date_of_birth": "1969-01-01"
    },
    {
      "given_name": "JANE",
      "surname": "HALLIWELL",
      "date_of_birth": "1968-09-02"
    },
    {
      "given_name": "JILLY",
      "surname": "HALL",
      "date_of_birth": "1971-05-01"
    },
    {
      "given_name": "JILLY",
      "surname": "HALL",
      "date_of_birth": "1970-01-01"
    }
  ],
  "gender": {
    "code": "F",
    "desc": "Female"
  },
  "nationalities": "American, Irish",
  "religion": {
    "code": "ATHE",
    "desc": "Atheist"
  },
  "ethnicity": {
    "code": "W1",
    "desc": "White: Eng./Welsh/Scot./N.Irish/British"
  },
  "language": {
    "preferred_spoken": {
      "code": "LAV",
      "desc": "Latvian"
    },
    "interpreter_required": true
  },
  "csra": {
    "code": "HI",
    "desc": "High"
  },
  "convicted": true,
  "cro_number": "ADF567890",
  "imprisonment_status": {
    "code": "SENT03",
    "desc": "Adult Imprisonment Without Option CJA03"
  },
  "iep_level": {
    "code": "ENH",
    "desc": "Enhanced"
  },
  "diet": {
    "code": "DIAB",
    "desc": "Medical - Diabetic"
  },
  "security_category": {
    "code": "A",
    "desc": "Cat A"
  }
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Offender Not Found"
  }
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing noms_id"
  }
}

Get details
GET`/offenders/{noms_id}`

Returns general offender information.

Name	Type	Description
date_of_birth	Date (yyyy-mm-dd)	date of birth
given_name	String	given Name
middle_names	String	middle Names
surname	String	surname
title	String	title
suffix	String	suffix
gender	Code and description	gender
aliases	array	List of offender’s aliases (see below)
convicted	boolean	indicates whether the offender has been convicted or is on remand
cro_number	String	CRO Number
pnc_number	String	PNC Number
nationalities	String	nationalities
religion	Code and description	religion
ethnicity	Code and description	ethnicity
imprisonment_status	Code and description	imprisonmentStatus
iep_level	Code and description	iepLevel
diet	Code and description	diet
language	Language (see below)	language
csra	Code and description	csra
security_category	Code and description	categorisationLevel

Alias

Name	Type	Description
given_name	String	given Name
middle_names	String	middle Names
surname	String	surname
date_of_birth	Date (yyyy-mm-dd)	date of birth

Language

Name	Type	Description
preferred_spoken	Code and description	spoken language
interpreter_required	boolean	whether an interpreter is required

Code and description

Name	Type	Description
code	String	code (for mapping)
desc	String	description (for display)

URI Parameters

HideShow

noms_id: string (required) Example: A1417AE

Get location ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1417AE/location

RequestsSuccessfulUnknown offenderInvalid NOMS ID

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "establishment": {
    "code": "BMI",
    "desc": "BIRMINGHAM (HMP)"
  },
  "housing_location": {
    "description": "BMI-C-2-03",
    "levels": [
      {
        "type": "Wing",
        "value": "C"
      },
      {
        "type": "Landing",
        "value": "2"
      },
      {
        "type": "Cell",
        "value": "03"
      }
    ]
  }
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Offender Not Found"
  }
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing noms_id"
  }
}

Get location
GET`/offenders/{noms_id}/location`

Since the offender’s location can change often and is fairly sensitive (and therefore should not automatically be exposed to all services), this information is not included in the general offender information call.

The levels shows the type of each level of the location address as defined on the Agency Details tab in Maintain Agency Locations screen (OUMAGLOC).

URI Parameters

HideShow

noms_id: string (required) Example: A1417AE

Get photograph ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1417AE/image

RequestsSuccessfulWhen the offender does not have a photoUnknown offenderInvalid NOMS ID

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "image": "<base64_encoded_jpeg_data>"
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "image": null
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Offender Not Found"
  }
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing noms_id"
  }
}

Get photograph
GET`/offenders/{noms_id}/image`

Returns a 480wx600h JPEG photograph of the offender. The data is base64 encoded within the image key.

URI Parameters

HideShow

noms_id: string (required) Example: A1417AE

Get charges ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1417AE/charges

RequestsSuccessfulWhen the offender does not have any chargesUnknown offenderInvalid NOMS ID

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "bookings": [
    {
      "booking_no": "A00018",
      "booking_active": true,
      "booking_started": "2012-10-11",
      "legal_cases": [
        {
          "case_active": true,
          "case_started": "2016-10-17",
          "court": {
            "code": "ABDRCT",
            "desc": "Aberdare County Court"
          },
          "legal_case_type": {
            "code": "A",
            "desc": "Adult"
          },
          "charges": [
            {
              "statute": {
                "code": "PL96",
                "desc": "Police Act 1996"
              },
              "offence": {
                "code": "PL96001",
                "desc": "Assault a constable in the execution of his / her duty"
              },
              "most_serious": true,
              "charge_active": true,
              "severity_ranking": "100",
              "result": {
                "code": "1002",
                "desc": "Imprisonment"
              },
              "disposition": {
                "code": "F",
                "desc": "Final"
              },
              "convicted": true,
              "imprisonment_status": {
                "code": "UNK_SENT",
                "desc": "Unknown Sentenced"
              },
              "band": {
                "code": "2",
                "desc": "Sent-Determinate NonFine"
              }
            }
          ]
        }
      ]
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "bookings": [
    {
      "booking_active": true,
      "booking_no": "A00063",
      "booking_started": "2016-08-31",
      "legal_cases": []
    }
  ]
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Offender Not Found"
  }
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing noms_id"
  }
}
FORMAT: 1A
HOST: https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Get charges
GET`/offenders/{noms_id}/charges`

Returns all the bookings, the legal cases for each booking and charges within each legal case.

The ordering is as follows:

bookings: Current or latest booking first, others in descending order of booking date
legal_cases: Active cases followed by inactive cases, further ordered by begin_date, latest first
charges: Most serious active charge first, then remaining active charges, followed by inactive charges

URI Parameters

HideShow

noms_id: string (required) Example: A1417AE

Alerts ¶

Fetch alerts by offender ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1583AE/alerts/?modified_since=2017-10-07T12:23:45.678&alert_type=H&include_inactive=true

RequestsSuccessfulSuccessful - Include InactiveUnsuccesful - Invalid Noms IdUnsuccesful - Offender not found

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "alerts": [
    {
      "alert_type": {
        "code": "X",
        "desc": "Security"
      },
      "alert_sub_type": {
        "code": "XEL",
        "desc": "Escape List"
      },
      "alert_date": "2018-01-12",
      "status": "ACTIVE",
      "comment": "has a large poster on cell wall"
    },
    {
      "alert_type": {
        "code": "R",
        "desc": "Risk"
      },
      "alert_sub_type": {
        "code": "RKS",
        "desc": "Risk to Known Adult - Custody"
      },
      "alert_date": "2018-01-12",
      "expiry_date": "2018-03-12",
      "status": "ACTIVE"
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "alerts": [
    {
      "alert_type": {
        "code": "X",
        "desc": "Security"
      },
      "alert_sub_type": {
        "code": "XEL",
        "desc": "Escape List"
      },
      "alert_date": "2018-01-12",
      "status": "ACTIVE",
      "comment": "has a large poster on cell wall"
    },
    {
      "alert_type": {
        "code": "R",
        "desc": "Risk"
      },
      "alert_sub_type": {
        "code": "RKS",
        "desc": "Risk to Known Adult - Custody"
      },
      "alert_date": "2018-01-12",
      "expiry_date": "2018-03-12",
      "status": "ACTIVE"
    },
    {
      "alert_type": {
        "code": "H",
        "desc": "Self Harm"
      },
      "alert_sub_type": {
        "code": "HA",
        "desc": "ACCT Open (HMPS)"
      },
      "alert_date": "2017-11-13",
      "expiry_date": "2018-01-12",
      "status": "INACTIVE"
    }
  ]
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing noms_id"
  }
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
     "error": {
         "message": "Offender Not Found"
     }
 }
FORMAT: 1A
HOST: https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Fetch alerts by offender
GET`/offenders/{noms_id}/alerts/{?modified_since,alert_type,include_inactive}`

Returns all active alerts for the specified offender or those that meet the optional criteria. Active alerts are listed first, followed by inactive alerts, both sorted by ascending order of alert date.

if alert_type is specified then only alerts of that type are returned
if modified_since is specified then only those alerts created or modified on or after the specified date time. The following formats are supported: 2018-01-10, 2018-01-10 03:34, 2018-01-10 03:34:12, 2018-01-10 03:34:12.123
If include_inactive=true is specified then inactive alerts are also returned.

Data Fields

Field	Description
alert_type	Code and description identifying the type of alert
alert_sub_type	Code and description identifying the sub type of alert
alert_date	Date the alert became effective
expiry_date	Date on which the alert expires or expired (optional)
status	ACTIVE or INACTIVE (Inactive alerts will have a expiry date of today or earlier
comment	free text comment

URI Parameters

HideShow

noms_id: string (required) Example: A1583AE
modified_since: datetime (optional) Example: 2017-10-07T12:23:45.678
alert_type: string (optional) Example: H
include_inactive: boolean (optional) Example: true

Financials ¶

Amounts are in all cases represented as an integer number of pence.

Account ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1404AE/accounts

RequestsSuccessful

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "spends": 5343,
  "cash": 0,
  "savings": 0
}

Account
GET`/prison/{prison_id}/offenders/{noms_id}/accounts`

Retrieve an offender’s financial account balances.

Returns balances for the offender’s three sub accounts (Spends, Saves and Cash) for the specified prison.

URI Parameters

HideShow

noms_id: string (required) Example: A1404AE
prison_id: string (required) Example: BMI

Transactions ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1404AE/accounts/spends/transactions?from_date=2016-01-01&to_date=

RequestsSuccessfulWhen requesting transaction history for the offender at another prisonWhen to_date is prior to the from_dateWhen account_code does not exist

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "transactions": [
    {
      "id": "6179142-1",
      "type": {
        "code": "CANT",
        "desc": "Canteen Spend"
      },
      "description": "1001118",
      "amount": "-28",
      "date": "2016-11-24"
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "transactions": []
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid query parameter to_date"
  }
}

This response has no content.

Responses400

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Invalid or missing path parameter account_code"
  }
}

Transactions
GET`/prison/{prison_id}/offenders/{noms_id}/accounts/{account_code}/transactions{?from_date,to_date}`

Retrieve an offender’s financial transaction history

Note: Transactions are be ordered in the NOMIS order. (Descending order of date followed by id).

URI Parameters

HideShow

noms_id: string (required) Example: A1404AE
prison_id: string (required) Example: BMI
account_code: string (required) Example: spends
Choices: spends savings cash
from_date: string (required) Example: 2016-01-01
to_date: string (optional)
Default is today

Record transaction ¶

POST https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1404AE/transactions

RequestsSuccessful

Headers

Content-Type: application/json

Body

{
  "type": "Hello, world!",
  "description": "Hello, world!",
  "amount": 1,
  "client_transaction_id": "Hello, world!",
  "client_unique_ref": "Hello, world!"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Valid transaction type for the prison_id"
    },
    "description": {
      "type": "string",
      "description": "Up to 240 characters"
    },
    "amount": {
      "type": "number"
    },
    "client_transaction_id": {
      "type": "string",
      "description": "Up to 12 characters"
    },
    "client_unique_ref": {
      "type": "string",
      "description": "A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, '-' and '_' are allowed (see [client_unique_ref](#client_unique_ref))"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "6179604-1"
}

Record transaction
POST`/prison/{prison_id}/offenders/{noms_id}/transactions`

Post a financial transaction to Nomis.

This will be setup by script intially as part of the deployment process as shown below.

Transaction Type	Description	Digital Prison	Non Digital Prison
CANT	Canteen Spend	Yes	No
REFND	Canteen Refund	Yes	No
PHONE	Phone Credit	Yes	No
MRPR	Misc Receipt - Private Cash	Yes	Yes
MTDS	Money through digital service	Yes	Yes
DTDS	Disbursement through Digital service	Yes	Yes
CASHD	Cash Disbursement	Yes	Yes
RELA	Money to Relatives	Yes	Yes
RELS	Money to Relatives- Spends	Yes	Yes

Notes:

The sub_account the amount is debited or credited from will be determined by the transaction_type definition in NOMIS.
If the field X-Client-Name is present in the request header then the value is prepended to the client_unique_ref separated by a dash. When this API is invoked via the Nomis gateway this will already have been created by the gateway.
The client_unique_ref can have a maximum of 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ characters are allowed

The following error conditions are reported

Insufficient Funds - The prisoner has insufficient funds in the required account to cover the cost of the debit transaction (Http Status 400)
Offender not in specified prison - prisoner identified by {noms_id} is not in prison {prison_id} (Http Status 400)
Invalid transaction type - The transaction type has not been set up for the API for {prison_id} (Http Status 400)
Finance Exception - An unexpected error has occurred. Details will have been logged in the nomis_api_logs table on the Nomis database.(Http Status 400)
Duplicate post - The unique_client_ref has been used before (Http status 409)

URI Parameters

HideShow

noms_id: string (required) Example: A1404AE
prison_id: string (required) Example: BMI

Get transaction ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1404AE/transactions/1234567890123

RequestsSuccessfulWhen transaction does not exist

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "6183748-1",
  "type": {
    "code": "CANT",
    "desc": "Canteen Spend"
  },
  "description": "Money to Prisoner via API",
  "amount": "-167",
  "date": "2017-03-28"
}

This response has no content.

Responses404

Headers

Content-Type: application/json

Body

{
  "error": {
    "message": "Transaction not found"
  }
}

Get transaction
GET`/prison/{prison_id}/offenders/{noms_id}/transactions/{client_unique_ref}`

Retrieve a posted transaction using the client unique reference (see client_unique_ref)

URI Parameters

HideShow

noms_id

string (required) Example: A1404AE

prison_id

string (required) Example: BMI

client_unique_ref

string (required) Example: 1234567890123

Client unique reference

this is the value specified in the body of the POST and should not include the X-Client-Name see note above.

Post pay event ¶

POST https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1404AE/payment

RequestsSuccessful

Headers

Content-Type: application/json

Body

{
  "type": "A_EARN",
  "description": "Hello, world!",
  "amount": 1,
  "client_transaction_id": "Hello, world!"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "A_EARN",
        "ADJ"
      ]
    },
    "description": {
      "type": "string",
      "description": "Up to 240 characters"
    },
    "amount": {
      "type": "number"
    },
    "client_transaction_id": {
      "type": "string",
      "description": "Up to 12 characters"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "Payment accepted"
}

Post pay event
POST`/prison/{prison_id}/offenders/{noms_id}/payment`

Pay events will be stored in a table on receipt by Nomis to be processed by a batch job scheduled to run after the last Nomis payroll batch job but before the advances and scheduled payments batch jobs.

Possible payment types are:

A_EARN: Credit, Offender Payroll
ADJ: Debit, Adjudication Award

URI Parameters

HideShow

noms_id: string (required) Example: A1404AE
prison_id: string (required) Example: BMI
The prison must be setup with an ‘Establishment Type’ of ‘Digital Prison’ for the post to be successful.

Hold an Amount ¶

POST https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1513AE/holds

RequestsSuccessful

prison_id: BMI (string)
noms_id: A1513AE (string)

Headers

Content-Type: application/json

Body

{
  "description": "Hold via API",
  "amount": 150,
  "reference_no": "TEST0076",
  "hold_until_date": "2017-07-07",
  "client_unique_ref": "seadiver"
}

Responses200

Headers

Content-Type: application/json

Body

{
  "hold-number": 6185874
}

Hold an Amount
POST`/prison/{prison_id}/offenders/{noms_id}/holds`

Places a hold on an offender account to prevent the disbursement of funds that are committed to a specific use.

Functionality is based on Nomis Hold Trust Screen (OTDHOLDT).

A transaction is created on Nomis with a transaction type of Hold (HOA). The hold balance on the offender’s private cash sub account and trust account is incremented by the hold amount and the available balance on the same accounts decremented by the same amount.

Note: The hold is not removed automatically on the Hold Until Date.

description - a description of the hold transaction
amount - The amount of money to be held
reference_no - a reference number for this transaction up to a maximum of twelve characters
hold_until_date - the date when the hold is to end
client_unique_ref (string, optional) - A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ are allowed (see client_unique_ref)

Errors

The following error conditions are reported

Response Status 404

Offender Not Found

No offender matching the specified offender_id has been found on nomis.

If this occurs it will be the only error reported.

Response Status 409

Duplicate Post

A transaction already exists with the client_unique_ref provided.

If this occurs it will be the only error reported.

Response Status 400

Hold Amount Cannot exceed the Balance Amount

Hold amount cannot be greater than the current balance in the offender’s cash account.
There is no balance available in the Sub account

The offender’s cash account has no balance
Hold date should be greater than current date

The hold_until_date must be greater than the current date
Sub account does not exist

This indicates a problem with the transaction operation setup and should not occur in normal operation
Finance Exception.

This indicates an unexpected financial problem, check the nomis_api_log table for details.

URI Parameters

HideShow

prison_id: string (required) Example: BMI
noms_id: string (required) Example: A1513AE

Get Holds ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1513AE/holds?client_unique_ref=

RequestsSuccessful

Headers

Content-Type: application/json

Body

+ prison_id: BMI (string)
+ noms_id: A1513AE (string)

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "hold_number": 6185835,
    "reference_no": "TEST0071",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 1000
  },
  {
    "hold_number": 6185839,
    "client_unique_ref": "angeline",
    "reference_no": "TEST0073",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 1300
  },
  {
    "hold_number": 6185843,
    "client_unique_ref": "thejourney",
    "reference_no": "TEST0074",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 1400
  },
  {
    "hold_number": 6185846,
    "client_unique_ref": "themoonupstairs",
    "reference_no": "TEST0075",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 1500,
    "hold_until_date": "2017-07-07"
  },
  {
    "hold_number": 6185862,
    "client_unique_ref": "jerkincrocus",
    "reference_no": "TEST0075",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 1500,
    "hold_until_date": "2017-07-07"
  },
  {
    "hold_number": 6185874,
    "client_unique_ref": "seadiver",
    "reference_no": "TEST0076",
    "description": "Hold via API",
    "entry_date": "2017-06-23",
    "amount": 150,
    "hold_until_date": "2017-07-07"
  }
]

Get Holds
GET`/prison/{prison_id}/offenders/{noms_id}/holds{?client_unique_ref}`

Gets every hold on an offender’s account or just the hold identified by the client_unique_ref

URI Parameters

HideShow

prison_id: string (required) Example: BMI
noms_id: string (required) Example: A1513AE
client_unique_ref: string (optional)
Client Unique reference (see client_unique_ref)

Release a Held Amount ¶

PUT https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1513AE/holds/6185837/release

RequestsSuccessful

Headers

Content-Type: application/json

Body

+ prison_id: BMI (string)
+ noms_id: A1513AE (string)
+ hold_number: 6185837 (integer)

Responses200

Headers

Content-Type: application/json

Body

{
  "message": "Hold released"
}

Release a Held Amount
PUT`/prison/{prison_id}/offenders/{noms_id}/holds/{hold_number}/release`

Releases the specified hold.

Functionality is based on Nomis Hold removal Window (OTUHOLDR).

A transaction is created on Nomis with a transaction type of Remove Hold (HOR). The hold balance on the offender’s private cash sub account and trust account is decremented by the hold amount and the available balance on the same accounts incremented by the same amount.

description - a description of the hold transaction

URI Parameters

HideShow

prison_id: string (required) Example: BMI
noms_id: string (required) Example: A1513AE
hold_number: integer (required) Example: 6185837

Record transaction at previous Prison ¶

POST https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/offenders/A1513AE/transfer_transactions

RequestsSuccessful - Offender releasedSuccessful - Offender in another prison

previous_prison_id: BMI (string)
noms_id: A1513AE (string)

Headers

Content-Type: application/json

Body

{
  "type": "MTDS",
  "description": "Money to Prisoner via API",
  "amount": 12700,
  "client_transaction_id": "TEST0063"
}

Responses200

Headers

Content-Type: application/json

Body

{
  "current_location": {
    "code": "OUT",
    "desc": "OUTSIDE"
  },
  "transaction": {
    "id": "6188552-1"
  }
}

previous_prison_id: LEI (string)
noms_id: A1417AE(string)

Headers

Content-Type: application/json

Body

{
  "type": "MTDS",
  "description": "Money to Prisoner via API",
  "amount": 12700,
  "client_transaction_id": "TEST0063"
}

Responses200

Headers

Content-Type: application/json

Body

{
     "current_location": { "code": "BMI", "desc": "BIRMINGHAM (HMP)" },
     "transaction": { "id": "6188554-1" }
  }
FORMAT: 1A
HOST: https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Record transaction at previous Prison
POST`/prison/{previous_prison_id}/offenders/{noms_id}/transfer_transactions`

Post a financial transaction to Nomis to a prison that the offender is no longer at.

The valid prison_id and type combinations are defined in the Nomis transaction_operations table which is maintained by the Maintain Transaction Operations screen (OCMTROPS), from the Financials Maintenance menu. Only those prisons (Caseloads) and Transaction types associated with the NOMISAPI module are valid. Only Transaction types with a usage of R (Receipt) are valid. Transaction Types are maintained via the Maintain Transaction Types screen (OCMTRANS).

Transaction is posted to the specified prison. if the account has been closed at this prison then it is re-opened first.

If the offender has been transferred to another prison then the funds are transferred to this prison.

If the account was previously closed then it will be closed again.

If the offender has been released then the funds are transferred to NACRO. Based on the Nomis Clear Inactive accounts screen (OTDCLINA).

type - transaction type
description - a description of the transaction
amount - The amount of money
reference_no - a reference number for this transaction up to a maximum of twelve characters
client_unique_ref (string, optional) - A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ are allowed (see client_unique_ref)

Errors

The following error conditions are reported

Response Status 404

Offender Not Found

No offender matching the specified offender_id has been found on nomis.
Offender never at prison

The offender has never been at the specified prison

Response Status 409

Duplicate Post

A transaction already exists with the client_unique_ref provided.

Response Status 400

Invalid transaction type

The transaction type has not been set up for the API for {prison_id}
Finance Exception.

This indicates an unexpected financial problem, check the nomis_api_log table for details.
Only receipt transaction types allowed

Only transaction types with a transaction usage of Receipt are allowed.
Sum of sub account balances not equal to current balance

The sum of all the sub account balances does equal the current balance held for the trust account
Offender being transferred

The offender is currently in transit
Offender still in specified prison

The offender is still at the specified prison. Use Record Transaction instead.

Response Status 500

Financial setup error

There is a problem with the transaction operations set up.

URI Parameters

HideShow

previous_prison_id: string (required) Example: BMI
noms_id: string (required) Example: A1513AE

Fetching live roll ¶

Offender list ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/prison/BMI/live_roll

RequestsSuccessful

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "noms_ids": [
    "A1404AE",
    "A1406AE"
  ]
}

Offender list
GET`/prison/{prison_id}/live_roll`

URI Parameters

HideShow

prison_id: string (required) Example: BMI

Offender details ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/A1404AE/pss_detail

RequestsSuccessful

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{}
FORMAT: 1A
HOST: https://gateway.nomis-api.service.justice.gov.uk/nomisapi

Offender details
GET`/offenders/{noms_id}/pss_detail`

URI Parameters

HideShow

noms_id: string (required) Example: A1404AE

Event feed ¶

Fetch events ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/offenders/events?prison_id=BMI&offender_id=A1492AE&event_type=RECEPTION&from_datetime=2017-08-20 10:56:27.627&limit=100

RequestsAll eventsALERTDISCHARGEIEP_CHANGEDINTERNAL_LOCATION_CHANGEDNOMS_ID_CHANGEDPERSONAL_DETAILS_CHANGEDPERSONAL_OFFICER_CHANGEDRECEPTIONSENTENCE_INFORMATION_CHANGEDBALANCE_UPDATE

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "ALERT",
      "id": 42,
      "timestamp": "2016-10-21T16:18:32.584Z",
      "noms_id": "A1470AE",
      "prison_id": "BMI"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "events": {
      "type": "array"
    }
  }
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "ALERT",
      "id": 41,
      "timestamp": "2016-10-21 16:18:32.584",
      "noms_id": "A1470AE",
      "prison_id": "BMI",
      "alert": {
        "offender_details": {
          "warnings": [
            {
              "warning_type": {
                "code": "X",
                "desc": "Security"
              },
              "warning_sub_type": {
                "code": "XB",
                "desc": "Bully"
              },
              "warning_date": "2016-10-21 00:00:00",
              "status": "ACTIVE"
            }
          ]
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "DISCHARGE",
      "id": 421,
      "timestamp": "2016-11-10 15:31:39.42",
      "noms_id": "A1477AE",
      "prison_id": "BMI",
      "discharge": {
        "discharge_status": {
          "discharge_datetime": "2016-11-10 15:31:38",
          "discharge_reason": {
            "code": "MRG",
            "desc": "Administrative Release due to Merge"
          }
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "IEP_CHANGED",
      "id": 21,
      "timestamp": "2016-10-21 15:55:06.284",
      "noms_id": "A1470AE",
      "prison_id": "BMI",
      "iep_changed": {
        "offender_details": {
          "entitlement": {
            "iep_level": {
              "code": "BAS",
              "desc": "Basic"
            }
          }
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "INTERNAL_LOCATION_CHANGED",
      "id": 541,
      "timestamp": "2016-11-22 14:35:48.558",
      "noms_id": "A1481AE",
      "prison_id": "BMI",
      "internal_location_changed": {
        "offender_details": {
          "location": {
            "internal_location": "BMI-C-3-05"
          }
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "NOMS_ID_CHANGED",
      "id": 901,
      "timestamp": "2016-11-25 15:46:21.720",
      "noms_id": "<OLD_NOMS_ID>",
      "prison_id": "BMI",
      "noms_id_changed": {
        "noms_id_change": {
          "old_noms_id": "Z1479AE",
          "new_noms_id": "A1479AE"
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "PERSONAL_DETAILS_CHANGED",
      "id": 1372,
      "timestamp": "2016-12-05 14:16:09.805",
      "noms_id": "A1497AE",
      "prison_id": "BMI",
      "personal_details_changed": {
        "offender_details": {
          "personal_details": {}
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "PERSONAL_OFFICER_CHANGED",
      "id": 1377,
      "timestamp": "2016-12-05 14:22:07.773",
      "noms_id": "A1497AE",
      "prison_id": "BMI",
      "personal_officer_changed": {
        "offender_details": {
          "case_details": {
            "personal_officer": "Hickinbotham, Jilly"
          }
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "RECEPTION",
      "id": 1361,
      "timestamp": "2016-12-05 14:03:14.292",
      "noms_id": "A1497AE",
      "prison_id": "BMI",
      "reception": {
        "offender_details": {
          "personal_details": {
            "offender_surname": "GATWICK",
            "offender_given_name_1": "GARY",
            "offender_dob": "1972-02-02 00:00:00",
            "gender": {
              "code": "F",
              "desc": "Female"
            },
            "diet": {
              "code": "DIAB",
              "desc": "Medical - Diabetic"
            },
            "religion": {
              "code": "ADV",
              "desc": "Adventist"
            },
            "security_category": {
              "code": "C",
              "desc": "Cat C"
            },
            "nationality": {
              "code": "BRIT",
              "desc": "British"
            },
            "language": {
              "code": "ENG",
              "desc": "English"
            },
            "ethnicity": {
              "code": "W1",
              "desc": "White: Eng./Welsh/Scot./N.Irish/British"
            }
          },
          "sentence_information": {
            "reception_arrival_date_and_time": "2016-12-05 14:02:00",
            "status": "Remand",
            "imprisonment_status": {
              "code": "RX",
              "desc": "Remanded to Magistrates Court"
            }
          },
          "location": {
            "agency_location": "BMI"
          },
          "warnings": [
            {
              "warning_type": {
                "code": "H",
                "desc": "Self Harm"
              },
              "warning_sub_type": {
                "code": "HA",
                "desc": "ACCT Open (HMPS)"
              },
              "warning_date": "2016-12-05 00:00:00",
              "status": "ACTIVE"
            }
          ],
          "entitlement": {
            "canteen_adjudication": false,
            "iep_level": {
              "code": "STD",
              "desc": "Standard"
            }
          }
        },
        "case_details": {
          "personal_officer": "Brady, Phill"
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "SENTENCE_INFORMATION_CHANGED",
      "id": 1365,
      "timestamp": "2016-12-05 14:07:50.215",
      "noms_id": "A1497AE",
      "prison_id": "BMI",
      "sentence_information_changed": {
        "offender_details": {
          "sentence_information": {
            "status": "Remand",
            "imprisonment_status": {
              "code": "UNKNOWN",
              "desc": "Disposal Not Known"
            }
          }
        }
      }
    }
  ]
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "events": [
    {
      "type": "BALANCE_UPDATE",
      "id": 4218,
      "noms_id": "A1471AE",
      "prison_id": "BMI",
      "timestamp": "2017-07-23 22:00:01.159",
      "balance_update": {
        "account": {
          "code": "REG",
          "desc": "Private Cash"
        },
        "balance": 0
      }
    },
    {
      "type": "BALANCE_UPDATE",
      "id": 4219,
      "noms_id": "A1471AE",
      "prison_id": "BMI",
      "timestamp": "2017-07-23 22:00:01.162",
      "balance_update": {
        "account": {
          "code": "SPND",
          "desc": "Spends"
        },
        "balance": 8.45
      }
    }
  ]
}

Fetch events
GET`/offenders/events{?prison_id,offender_id,event_type,from_datetime,limit}`

Returns all events that required to update the prisoner self service application. Currently these are:

ALERT
DISCHARGE
IEP_CHANGED
INTERNAL_LOCATION_CHANGED
NOMS_ID_CHANGED
PERSONAL_DETAILS_CHANGED
PERSONAL_OFFICER_CHANGED
RECEPTION
SENTENCE_INFORMATION_CHANGED
BALANCE_UPDATE

URI Parameters

HideShow

prison_id: string (optional) Example: BMI
offender_id: string (optional) Example: A1492AE
event_type: string (optional) Example: RECEPTION
from_datetime: datetime (optional) Example: 2017-08-20 10:56:27.627
limit: number (optional) Example: 100

System Information ¶

Fetch Version Information ¶

GET https://gateway.nomis-api.service.justice.gov.uk/nomisapi/version?show=

RequestsSuccessfulDatabase Info

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "api-version": "1.13.0",
  "build-timestamp": "2017-05-24 16:53:32"
}

This response has no content.

Responses200

Headers

Content-Type: application/json

Body

{
  "api-version": "1.13.0",
  "build-timestamp": "2017-05-24 16:53:32",
  "database-name": "PVB_DEV",
  "database-release-levels": {
    "DB Patch Level": "DB_V11.2.1.1.48",
    "xTAG Patch Level": "XTAG_V11.2.1.1.2",
    "SYS Patch Level": "SYS_V10.2.2.5.3",
    "Reference Data Level": "RD_V11.2.1.1.11"
  },
  "database-packages": [
    {
      "owner": "API_OWNER",
      "package": "API_BOOKING_PROCS",
      "valid": true,
      "version": "1.0   11-Jan-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_CORE_PROCS",
      "valid": true,
      "version": "5.4   29-Sep-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "API_DATA_EXTRACTOR",
      "valid": true,
      "version": "1.0   10-Apr-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_EVENTS",
      "valid": true,
      "version": "1.0   10-Apr-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_FINANCE_PROCS",
      "valid": true,
      "version": "1.6   27-Mar-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_LEGAL_PROCS",
      "valid": true,
      "version": "1.0   11-Jan-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_METADATA",
      "valid": true,
      "version": "1.0   18-May-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_OFFENDER_EVENT",
      "valid": true,
      "version": "1.0   19-Oct-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "API_OFFENDER_PROCS",
      "valid": true,
      "version": "1.3   20-Jan-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "API_PRISON_PROCS",
      "valid": true,
      "version": "1.0   15-Nov-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "API_VISIT_PROCS",
      "valid": true,
      "version": "1.12   26-Apr-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "CORE_UTILS",
      "valid": true,
      "version": "1.4   08-Mar-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "JSON_BUILDER",
      "valid": true,
      "version": "1.2   07-Apr-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "NOMIS_API_BATCH",
      "valid": true,
      "version": "1.1   30-Nov-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "NOMIS_API_LOG",
      "valid": true,
      "version": "1.0   21-Oct-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "PSS_DATA_EXTRACTOR",
      "valid": true,
      "version": "1.2   10-Apr-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "PSS_EVENTS",
      "valid": true,
      "version": "1.1   16-Dec-2016"
    },
    {
      "owner": "API_OWNER",
      "package": "PSS_EVENTS_XX",
      "valid": false,
      "version": null
    },
    {
      "owner": "API_OWNER",
      "package": "SOI_HTTP_UTILS",
      "valid": true,
      "version": "5.6   14-Feb-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "SOI_JSON",
      "valid": true,
      "version": "5.8   03-Mar-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "SOI_OUT_LOG",
      "valid": true,
      "version": "5.2   12-Jan-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "SOI_QUEUE_PROCS",
      "valid": true,
      "version": "5.5   27-Jan-2017"
    },
    {
      "owner": "API_OWNER",
      "package": "SOI_UTILS",
      "valid": true,
      "version": "5.3   19-Jan-2017"
    }
  ]
}

Fetch Version Information
GET`/version{?show}`

Returns the version of the API running.

This returns the version of the API and the data and time that the war file was built.

Optionally, it returns information from the connected database:

The service name of the database
The Syscon release levels
The status and version numbers of the packages used by the API.

URI Parameters

HideShow

show: string (optional)
Choices: database

Notes ¶

client_unique_ref

Where implemented this allows a client application to provide a unique reference (client_unique_ref) as part of a POST transaction, such that if the POST transaction is repeated with the same client_unique_ref the transaction will fail and return an Http status of 409 and a Duplicate Post error message.

client_unique_ref (string, optional) - A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ are characters allowed.

To guard against the situation where more than one client application coincidentally uses the same client_unique_ref the value contained in the request header field X-Client-Name is prepended to the client_unique_ref separated by a dash. When the API is invoked via the Nomis gateway as will be the case in normal operation, then this X-Client-Name will already have been created by the gateway.

If the X-Client-Name field is not present in the request header then the client_unique_ref will be used as provided.

The same applies when a client_unique_ref is used a query parameter on a GET transaction.

Example

X-Client-Name = syscon-dev-client
client_unique_ref = a1d2f3c5bf
resultant value = syscon-dev-client-a1d2f3c5bf

When returning a client_unique_ref in a response body, the X-Client-Name should not be returned to the client application and the client applications should only receive its own client_unique_refs.

If the X-Client-Name is present in the header and matches the beginning of the client_unique_ref then it will be stripped off before returning.
If the X-Client-Name is present in the header and doesn’t match the begining of the client_unique_ref then the client_unique_ref will not be returned.
If the X-Client-Name is not present in the header then the client_unique_ref will be returned as stored.

Generated by aglio on 30 Jan 2020

API Endpoint

Offender ¶

Get details ¶

Headers

Body

Headers

Body

Headers

Body

Get detailsGET/offenders/{noms_id}

Get location ¶

Headers

Body

Headers

Body

Headers

Body

Get locationGET/offenders/{noms_id}/location

Get photograph ¶

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get photographGET/offenders/{noms_id}/image

Get charges ¶

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get chargesGET/offenders/{noms_id}/charges

Alerts ¶

Fetch alerts by offender ¶

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Fetch alerts by offenderGET/offenders/{noms_id}/alerts/{?modified_since,alert_type,include_inactive}

Financials ¶

Account ¶

Headers

Body

Account GET/prison/{prison_id}/offenders/{noms_id}/accounts

Transactions ¶

Headers

Body

Headers

Body

Headers

Body

Headers

Body

TransactionsGET/prison/{prison_id}/offenders/{noms_id}/accounts/{account_code}/transactions{?from_date,to_date}

Record transaction ¶

Headers

Body

Schema

Headers

Body

Record transactionPOST/prison/{prison_id}/offenders/{noms_id}/transactions

Get transaction ¶

Headers

Body

Headers

Body

Get transactionGET/prison/{prison_id}/offenders/{noms_id}/transactions/{client_unique_ref}

Post pay event ¶

Headers

Body

Get details
GET`/offenders/{noms_id}`

Get location
GET`/offenders/{noms_id}/location`

Get photograph
GET`/offenders/{noms_id}/image`

Get charges
GET`/offenders/{noms_id}/charges`

Fetch alerts by offender
GET`/offenders/{noms_id}/alerts/{?modified_since,alert_type,include_inactive}`

Account
GET`/prison/{prison_id}/offenders/{noms_id}/accounts`

Transactions
GET`/prison/{prison_id}/offenders/{noms_id}/accounts/{account_code}/transactions{?from_date,to_date}`

Record transaction
POST`/prison/{prison_id}/offenders/{noms_id}/transactions`

Get transaction
GET`/prison/{prison_id}/offenders/{noms_id}/transactions/{client_unique_ref}`

Post pay event
POST`/prison/{prison_id}/offenders/{noms_id}/payment`

Hold an Amount
POST`/prison/{prison_id}/offenders/{noms_id}/holds`

Errors

Response Status 404

Response Status 409

Response Status 400

Get Holds
GET`/prison/{prison_id}/offenders/{noms_id}/holds{?client_unique_ref}`

Release a Held Amount
PUT`/prison/{prison_id}/offenders/{noms_id}/holds/{hold_number}/release`

Record transaction at previous Prison
POST`/prison/{previous_prison_id}/offenders/{noms_id}/transfer_transactions`

Errors

Response Status 404

Response Status 409

Response Status 400

Response Status 500

Offender list
GET`/prison/{prison_id}/live_roll`

Offender details
GET`/offenders/{noms_id}/pss_detail`