aviars/vmi-api.md

## vmi-api.md

      
    Raw
  

              vmi-api.md
            
          
    User Create/Modify User Quick Start - Consumer Directed Exchange

The following example illustrates how to create new users in the VerifyMyIdentity, a certified Open ID Connect (OIDC) Identity Provider. The following examples create Community Member accounts for purposes of Consumer Directed Exchange (CDeX).  These API calls are designed to be used by trusted 3rd party applications,
The field names and structure of the HTTP request\response  bodies mirror and build upon Open ID Connect (OIDC) https://openid.net/specs/openid-connect-core-1_0.html and the iGov Profile for OpenID Connect https://openid.net/specs/openid-igov-openid-connect-1_0-02.html
Create a User (Basic Example)

The following example illustrates a bare minimum require necessary to create a user for purposes of Consumer Directed exchange.

HTTP Method: POST
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/createuser
Authorization: OAuth2 Bearer Token

Example Request Body

{
"preferred_username": "james",
"given_name": "James",
"family_name": "Kirk",
"gender": "male",
"birthdate": "1952-01-03"
}

Discussion

The fields gender and birthdate are not strictly required to create an account but are necessary to enable patient-linking and matching to the individual's health records.   While not required. a password parameter may also be given in this request.  If the password is not set, the user will need to set their own password through some alternative workflow.  In this example, there are no claims being made about the user's identity assurance level (IAL), therefore the resulting IAL is 1(lowest trust).  In the next Enriched Example section we will create a more robust user from the start.
Example Request Response

A successful response HTTP 200 will return a similar structure to what was sent.:
{
"iss": "https://alpha.verifymyidentity.com",
"subject": "123456789012345",  
"username": "james",   
"given_name": "James",
"family_name": "Kirk",
"gender": "male",
"birthdate": "1952-01-03",
"ial": 1,
"id_assursance" : [],
"document" : [],
"address": []
}

Create a User (Enriched Example)

The following example illustrates an account creation with more demographic and identity infiormation.

HTTP Method: POST
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/user/
Authorization: OAuth2 Bearer Token

The following is an example request body:
{
	"iss": "https://alpha.verifymyidentity.com",
"subject": "123456789012345",  
"preferred_username": "james",
"given_name": "James",
"family_name": "Kirk",
"gender": "male",
"password": "tree garden jump fox,
"birthdate": "1952-01-03",
"nickname": "Jim",
"phone_number": "+15182345678",
"email": "jamess@example.com",
"ial": 1,

}
Request Response

A successful response HTTP 200:
{
"iss": "https://alpha.verifymyidentity.com",
"subject": "123456789012345", 
"preferred_username": "james",
"given_name": "James",
"family_name": "Kirk",
"name": "James Kirk",
"gender": "male",
"birthdate": "1952-01-03",
"nickname": "Jim",
"phone_number": "+15182345678",
"email": "jamess@example.com",
"ial": 1,
"id_assursance" : [],
"document" : [],
"address": []
 }

Modify a User's Date of Birth


HTTP Method: POST or PUT
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/user/[sub]
Authorization: OAuth2 Bearer Token

Adding a record of identifity verifieaction is how the IAL is calculated.  The sub is provided  as the identifer for the user record.
In most cases, the goal is to move a user's account from level 1 to level 2 for an extended period of time.
Request Endpoint: HTTP PUT /api/v1/user/123456789012345
Request Body:

{
"birthdate": "2233-03-22"
}

Example Response HTTP 200

{
    "sub": "123456789012345",
    "birthdate": "2233-03-22"
}

Adding\Modify Identity Assurance Level Evidence


HTTP Method: POST (tp create) amd PUT (to Modify)
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/user/[sub]
Authorization: OAuth2 Bearer Token

Adding a record of identifity verifieaction is how the IAL is calculated.  The sub is provided  as the identifer for the user record.
In most cases, the goal is to move a user's account from level 1 to level 2 for an extended period of time. The identity assurance level (IAL) claim contains:

The desired IAL level
A description of the evidence
A code classifiing the evidence. Codes include ONE-SUPERIOR-OR-STRONG+,ONE-STRONG-TWO-FAIR,TWO-STRONG,          TRUSTED-REFEREE-VOUCH, and KBA. See Nist SP 800-63-3 for details.
The subject identifier of the person acting as a trusted agent (if applicable).
The date of the identity verification check.

Request Endpoint: HTTP POST /api/v1/user/id-assurance/123456789012345
Request Body for Create

{
	"identity_assurance": [{
			"description": "NY Medicaid card.",
			"classification": "NE-SUPERIOR-OR-STRONG+",
            "exp": "2022-01-01",
			"verifier_subject": "876545671054321",
			"note": "A paper copy of the document is on file.",
			"verification_date": "2019-03-04"}]
}

Example Response for Create

{
    "sub": "123456789012345",
    ....
    "ial": "2",
	"identity_assurance": [{
            "uid": "97fb9995-fa8b-4719-9f55-65c1c5f4fd1b",
			"description": "NY Medicaid card.",
			"classification": "NE-SUPERIOR-OR-STRONG+",
			"verifier_subject": "876545671054321",
			"note": "A paper copy of the document is on file.",
			"verification_date": "2019-03-04"}]
     ...
 }

Request Endpoint: HTTP PUT /api/v1/user/id-assurance/123456789012345
Request Body for Update

In this exaample the expiration date is updated.
{
	"identity_assurance": [{
            "uid": "97fb9995-fa8b-4719-9f55-65c1c5f4fd1b",
			"description": "NY Medicaid card.",
			"classification": "NE-SUPERIOR-OR-STRONG+",
            "exp": "2028-12-12",
			"verifier_subject": "876545671054321",
			"note": "A paper copy of the document is on file.",
			"verification_date": "2019-03-04"}]
}

Example Response for Update

{
    "sub": "123456789012345",
    ....
    "ial": "2",
	"identity_assurance": [{
            "uid": "97fb9995-fa8b-4719-9f55-65c1c5f4fd1b",
			"description": "NY Medicaid card.",
			"classification": "NE-SUPERIOR-OR-STRONG+",
            "exp": "2028-12-12",
			"verifier_subject": "876545671054321",
			"note": "A paper copy of the document is on file.",
			"verification_date": "2019-03-04"}]
     ...
 }

Adding\Modify Identifiers


HTTP Method: POST (to create) PUT (to update)
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/user/identifer/[sub]
Authorization: OAuth2 Bearer Token

Identifiers are for adding master patient indexes and other types of pointers to an individuals.  Examples include, a Mediciad ID number, a driver's license numbers, and a patient ID to a particular online resource (e.g. FHIR)aa record of identifity verifieaction is how the IAL is calculated.  The sub is provided  as the identifer for the user record.
In most cases, the goal is to move a user's account from level 1 to level 2 for an extended period of time.
Adding a Mediciad ID number

Request Endpoint: HTTP POST /api/v1/user/identifier/123456789012345
Request Body for Create

        {
		"issuer": "New York Department of Health HHS Mediciad Duke Health Systems",
		"type": "MEDICIAD_ID_NY",
		"num": "9ASDFG2",
        "region": "NY"
	    }

Example Response for Create

{
    "sub": "123456789012345",
    "document":
        {
        "uid": "94474d22-0962-4a6b-89ba-cddbe3e3a8d4",
		"issuer": "New York Department of Health HHS Mediciad Duke Health Systems",
		"type": "MEDICIAD_ID_NY",
		"num": "9ASDFG2",
        "region": "NY"
	    }
     ...
 }

Adding a FHIR Pointers

In the folowing example, two patient ID's to consumer facing API's are added to the user's record.
The software_id field is used as the primary key to uniquely identify a given system. The issuer is a string describing the system.  The type identifies the type of the data contained in nu,  The endpoint' is the actual URL for the FHIR Resource server.  The num is the actual FHIR patient identier. Despit its name, it need not be a number.
Request

{
"document": [

	{
        "uid": "50efab40-fd26-4f75-b124-30e4cec93620",
		"issuer": "Health information Exchange of NY (HIXNY)",
		"software_id": "HIXNY-patient-api",
		"type": "FHIR_PATIENT_ID",
		"num": "123456789012345",
		"endpoint": "https://hixny.oauth2.io/fhir/patient/DSTU2/"
	},
	{
        "uid": "d64e9b97-2a5a-4e69-b400-ad059a8c1fc8",
		"issuer": "Duke Health Systems",
		"software_id": "Duke-Health-Systems-Patient-API",
		"type": "FHIR_PATIENT_ID",
		"num": "TGifRZDexrA8rYQWTmVU0e8G0VCpxGrspxW0dZ3Ls1owB",
		"endpoint": "https://health-apis.duke.edu/FHIR/patient/DSTU2/"
	}]

}

Response

{
"subject": "123456789012345",
...
"document": [
    {
        "uid": "94474d22-0962-4a6b-89ba-cddbe3e3a8d4",
		"issuer": "New York Department of Health HHS Mediciad Duke Health Systems",
		"type": "MEDICIAD_ID",
		"num": "9ASDFG2",
        "region": "NY"
	},
		{
        "uid": "50efab40-fd26-4f75-b124-30e4cec93620",
		"issuer": "Health information Exchange of NY (HIXNY)",
		"software_id": "HIXNY-patient-api",
		"type": "FHIR_PATIENT_ID",
		"num": "123456789012345",
		"endpoint": "https://hixny.oauth2.io/fhir/patient/DSTU2/"
	},
	{
        "uid": "d64e9b97-2a5a-4e69-b400-ad059a8c1fc8",
		"issuer": "Duke Health Systems",
		"software_id": "Duke-Health-Systems-Patient-API",
		"type": "FHIR_PATIENT_ID",
		"num": "TGifRZDexrA8rYQWTmVU0e8G0VCpxGrspxW0dZ3Ls1owB",
		"endpoint": "https://health-apis.duke.edu/FHIR/patient/DSTU2/"
	}]
 ...
}

Adding/Modifiing Addresses


HTTP Method: POST (to create) PUT (to update)
Body: application/json
Endpoint:https://alpha.verifymyidentity.com/api/v1/user/address/[sub]
Authorization: OAuth2 Bearer Token

Addresses are physical addresses.  This works just like the other APIs/
Request

{

"subject": "123456789012345",
"address": [
	{
        "formatted": "837 State St.\n Schenectady, NY 12307",
		"street_address": "516 Brookwood Dr. ",
		"locality": "Schenectady",
		"region": "NY",
		"postal_code": "12307",
		"country": "US"
	}
]
}

Response

A successful response HTTP 200:
{

"subject": "123456789012345",
"address": [
	{
		"uid": "6ef4a89a-b520-4dab-be3e-e1b9e2f4d722",
        "formatted": "837 State St.\n Schenectady, NY 12307",
		"street_address": "516 Brookwood Dr. ",
		"locality": "Schenectady",
		"region": "NY",
		"postal_code": "12307",
		"country": "US"
	}
]
	}
]
}