eesa-applicant-api.md

NCARB EESA API

This document describes the web api that NCARB will develop to enable EESA integration with NCARB's System.

The EESA system will rely on a scheduled task that will make requests nightly or hourly to the NCARB EESA API.

Security

All requests will be made over HTTPS and secured using Basic Authentication. NCARB will issue two sets of username/password pairs to access our test and production environments.

API Definitions

All api definitions are provided in JSON format. XML will also be supported. The content type of the response can be controlled by EESA by setting the Accept header in their requests. "application/json" and "application/xml" are supported

Applicants

Returns a list of all applicants and the status of their EESA application

Example

GET /api/eesa/applicants

[
	{
		"recordNumber":321456,
		"status":3
	},
	{
		"recordNumber":654321,
		"status":4
	},
	{
		"recordNumber":123456,
		"status":1
	}
]

Applicants by status

Returns a list of all applicants in particular status.

Possible status codes can be:

1. Payment Confirmed : Payment confirmed
2. Documents Confirmed: meaning EESA has received a complete packet
3. Assigned to Evaluator: meaning the documents are being evaluated
4. Evaluation Decision Posted: when letter is posted from EESA, this includes both Meets the Standard (pass) and Does not meet the Standard (fail).

Example

GET /api/eesa/applicants?status=4

Response Body

[
	{
		"recordNumber":321456,
		"status":4
	},
	{
		"recordNumber":654321,
		"status":4
	},
	{
		"recordNumber":123456,
		"status":4
	}
]

Applicant by NCARB record number

Returns detailed information about an eesa applicant by NCARB record number

Example

GET /api/eesa/applicants/321456

Response body

{
	"salutation":"null",
	"firstName":"Joe",
	"middleName":"P",
	"lastName":"Schmo",
	"status": 4,
	"degreeQualifiesForLicense": true,
	"gender":"Male",
	"email":"[email protected]",
	"countryOfCitizenship":"USA",
	"mailingAddress":
	{
		"street1":"1301 Maple Ave.",
		"street2":"Apt 4A",
		"country":"USA",
		"state":"MD",
		"city":"Baltimore",
		"zip":"21154",
		"primary":true
	},
	"phones":
	[	
		{
			"number":"+15445554444",
			"type":"Cell",
			"primary":true
		},
		{
			"number":"544-555-4443",
			"type":"Work",
			"primary":false
		}
	],
	"higherEducation":
	[
		{
			"description":"University of Waterloo",
			"datesAttended":
			{
				"start":"2001-12-02",
				"end":"2004-12-02",
			},
			"graduationDate":"2004-12-02",
			"degreeName":"Master of Landscape Architecture",
			"city":"Waterloo",
			"state":"ON",
			"country":"CAN"		
		},
		{
			"description":"California State Polytechnic University, San Luis Obispo",
			"datesAttended":
			{
				"start":"2005-12-02",
				"end":"2006-12-31",
			},
			"graduationDate":"2007-01-31",
			"degreeName":"Master of Science in Architecture in Engineering-Construction Management",
			"city":"San Luis Obispo",
			"state":"CA",
			"country":"USA"			
		}
	]
}

Status codes

• 200 OK
• 404 Not Found (there is no applicant with that number found)

Notes

Valid phone types are:

1. Cell
2. Home
3. Work

education will not include high school

Update applicant status

Example

this will place applicant in status 2 (Waiting for Transcript). NCARB will be responsible for updating the applicant via email that this change has occurred.

PUT /api/eesa/applicants/321456/status/2

Status codes

• 200 OK (the status of the applicant was succesfully updated)
• 403 Forbidden (the status code was not accepted)
• 404 Not Found (there is no applicant with that number found)

Upload a document

Example

POST /api/eesa/applicants/321456/documents?fileName=test.pdf&fileType=Evaluation
Content-Type: application/pdf
Content-Length: 67

%PDF-1.
trailer<</Root<</Pages<</Kids[<</MediaBox[0 0 3 3]>>]>>>>>>

Request body

The file contents to be uploaded. In the above example, the body is the contents of a pdf document.

The content-type header should match the file type (if known) or "application/octet-stream" if the format is not known to the uploader

Notes

Valid "File Types" are:

1. Evaluation
2. CreditSummary

The server will inspect the request body and determine the actual mime type. The server will reject any file that is determined to NOT be in a pdf format (400 Bad Request).

The server will also reject any file greater than 2MB in size. (413 Request Entity Too Large)

Status codes

• 202 Accepted (the document contents have been uploaded and will be processed later)
• 400 Bad Request (the request was invalid)
• 404 Not Found (there is no applicant with that number found)
• 411 Content-Length (the client did not specify a Content-Length head in the request)
• 413 Request Entity Too Large (the document is too large. 2MB will be the limit)