Submitting Orders

HumanAPI is a platform that enables people to access and share their medical records. Every person that we collect data for is considered a “user” in our system, and ordering evidence for an individual is accomplished by creating that individual as a user within the HumanAPI platform. At this time, creating a user and ordering medical evidence for that user are synonymous and are accomplished at the same time using a single /POST call to the admin endpoint.



This POST call is authorized using the client-token created in previous section.

The request looks like this:

POST /api/v1/users HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
Authorization : Bearer your-client-token 

  "orderType": "healthcheck",
  "clientUserId": "your-policy-number",
  "clientUserEmail": "[email protected]",
  "firstName": "Jane",
  "middleName": "A.",
  "lastName": "Doe",
  "gender": "female",
  "dateOfBirth": "1968-02-13T00:00:00.000Z",
  "suggestedSources": ["Maxwell Forrest M.D.", "Kindred hospital"],
  "ssn": "000-00-0000",
  "phone": "(555) 213-5555",
  "address": {
    "street1": "969-1762 Buttery Rd.",
    "street2": "6818 Eget St.",
    "city": "Boise",
    "state": "ID",
    "zip": "83712"

  "conditions": ["COPD", "Tobacco use"],
  "providers": [
      "name": "Maxwell Forrest M.D.",
      "organizationName": "Brentwood North Family Practice",
      "address": {
            "street1": "6818 Eget St.",
            "street2": "6818 Eget St.",
            "city": "Tacoma",
            "state": "WA",
            "zip": "98402"
      "phone": "(425) 288-2332",
      "fax": "(715) 912-6931",
      "mrn": "000TB0009-3"
      "organizationName": "Kindred hospital",
      "address": {
          "city": "Las Vegas",
          "state": "NV",
          "zip": "58521"
  "attachments" : [{
      "type": "hipaaAuthorization",
      "contentType": "application/pdf",
      "encoding": "base64",
      "content": "iVBORw0KGgoAAAANSUhEUgAABuoAAAYiCA..."


Request Body

The request body does not allow empty or null strings so if you do not have a value omit that property altogether.
For example is "street2" does not exist omit street2 property from the request payload

TODO: Describe properties of the schema in here.


Please read the order request specifications for a detailed reference of the request.

If the request is successful, you’ll get a response with status 202 and the user details in the body. A successful response to the request above should look like this:

  "clientUserId": "your-policy-number",
  "humanId": "ef14404e9860776f6300e3e4cb10f84a",
  "firstName": "Maxwell",
  "lastName": "Forrest",
  "dateOfBirth": "1968-02-13T00:00:00.000Z",    
  "suggestedSources": ["Max Forrest M.D.","Angel Memorial Hospital"],
  "createdAt": "2020-02-21T18:23:21.445Z",
  "updatedAt": "2020-02-21T18:23:21.445Z",    
  "status": "Invited",    
  "consumerLink": ""



The “status” field is deprecated for our latest version of the platform. Ignore this field.

The humanId attribute is Human API’s unique identifier for the user. Make sure that you keep it for later use.

Most order types include inviting the user to connect their medical records themselves via their patient portal. To facilitate this, the consumerLink attribute is the URL of the Task Manager, hosted by Human API, where the user can start the authorization process.

Response status codes

Response status codes are included below for reference:

202 - Accepted Request successful
400 - Bad request Invalid input and/or formatting
401 - Unauthorized Invalid, missing, or expired client token
500 - Internal Server Error Server issue processing the request