get-employment-status.bak.md

Get employment status

Checks the employment status of an individual in a payroll scheme.

Authorisation

OAuth 2.0 Bearer Token with the read:apprenticeship-levy scope.

API

GET https://api.service.hmrc.gov.uk/apprenticeship-levy/epaye/{empref}/employed/{nino}?fromDate={date}& toDate={date}

Request

Headers

Name	Value
Accept	application/vnd.hmrc.1.0+json
Authorization	Bearer [token here]

Path Parameters

Name	Type	Value	Example
empref	String	A valid (URL encoded) employer reference for the PAYE scheme.	123/AB12345
nino	String	A valid National Insurance Number (nino) for the individual being checked.	XY654321Z

Query Parameters

Name	Type	Value	Example
fromDate	Date	Starting date of the period to check employment for.	2016-01-31
toDate	Date	Ending date of the period to check employment for.	2016-01-31

Response

Successful Response

{
                "empref" : "123/AB12345",
                "nino" : "XY654321Z",
                "fromDate" : "2016-03-06",
                "toDate" : "2016-04-05",
                "employed" : true
}

Name	Type	Description	Example
empref	String	The PAYE Reference for the employer. This will be the same as provided in the URL.	123/AB12345
nino	String	The NINO of the individual being checked. This will be the same as provided in the URL.	XY654321Z
fromDate	Date	The start date of the range the check should be made for.	[2016-03-06]
toDate	Date	The end date of the range the check should be made for.	[2016-04-05]
employed	Boolean	Whether or not the individual was employed in the scheme at any time with the date range.	[true]

Error Responses

Code & Name	Value	Description	Example
400 Bad Request	BAD_REQUEST	A request parameter is incorrect or unknown, or from date is after to date.	{ "code": "BAD_REQUEST", "message": "From date was after to date" }
400 Bad Request	EMPREF_INVALID	Employer reference (EMPREF) request parameter is incorrect.	{ "statusCode": "400", "message": "EMPREF_INVALID: '...' is in the wrong format. Should be ^\\d{3}/[0-9A-Z]{1,10}$ and url encoded." }
400 Bad Request	DATE_INVALID	Date request parameter is incorrect.	{ "statusCode": "400", "message": "DATE_INVALID: '.....' date parameter is in the wrong format. Should be '^(\\d{4})-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$' where date is yyyy-MM-dd and year is 2000 or later." }
400 Bad Request	_400	Date(s) request parameter(s) is missing.	{ "statusCode": "400", "message": "Missing parameter: fromDate/toDate" }
400 Bad Request	EPAYE_EMPREF_INVALID	A request parameter is incorrect.	{ "code": "DES_ERROR", "message": "Auth unauthorised error: GET of '....' returned 401. Response body: ''" }
401 Unauthorized	INVALID_CREDENTIALS	The request requires correct authentication headers with valid token.	{ "code": "INVALID_CREDENTIALS", "message": "Invalid Authentication information provided" }
401 Unauthorized	DES_ERROR	The request requires user authentication. Please ensure Grant authority has been given and bearer token is supplied with the request headers.	{ "code": "DES_ERROR", "message": "Auth unauthorised error: GET of '...' returned 401. Response body: ''" }
403 Forbidden	DES_ERROR	The request requires user authentication. Please ensure Grant authority has been given and bearer token is supplied with the request headers.	{ "code": "DES_ERROR", "message": "Auth forbidden error: GET of '...' returned 403. Response body: ''" }
404 Not Found	EPAYE_UNKNOWN	Endpoint or internal system has become unavailable or either NINO or EMPREF are not found. EPAYE_NINO_UNKNOWN and EPAYE_EMPREF_UNKNOWN have been withdrawn as backend systems will not distinguish 404 errors between unknown NINO or unknown EMPREF.	{ "code": "EPAYE_UNKNOWN", "message": "The provided NINO or EMPREF was not recognised'" }
408 Request Time-out	DES_ERROR	Endpoint or internal system has become unresponsive.	{ "code": "DES_ERROR", "message": "Auth not responding error: GET of '...' timed out with message 'Request timeout to localhost/127.0.0.1:8080 after 500 ms'" }
429 Too many requests	DES_ERROR	Too many requests have been made to this endpoint	{ "code": "DES_ERROR", "message": "Too many requests" }
503 Service Unavailable	DES_ERROR	Endpoint or internal system has experienced an internal error.	{ "code": "DES_ERROR", "message": "Auth 5xx error: GET of '....' returned 500. Response body: ''" }