RelatedPerson

Information about a person that is involved in the care for a patient, but who is not the target of healthcare, nor has a formal responsibility in the care process.

https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-relatedperson.html

Endpoints

get
/RelatedPerson/{id}
 get
/RelatedPerson
get
/RelatedPerson/{id}

RelatedPerson read

Read a RelatedPerson resource.

Path Parameters

id required
string
The unique identifier for the RelatedPerson

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the RelatedPerson.

active
boolean

Whether this related person’s record is in active use.

patient
json

The patient this person is related to.

Click to view child attributes
reference
string

The reference string of the patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

Type the reference refers to (e.g. “Patient”).

relationship
array[json]

The nature of the relationship.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/v3-RoleCode
  • Empty string
code
string

The code of the relationship.

Values are nominally from the PatientRelationshipType ValueSet, but custom contact categories can be used as well.

display
string

The display name of the coding.

Values are nominally from the PatientRelationshipType ValueSet, but custom contact categories can be used as well.

name
array[json]

A name associated with the person.

Click to view child attributes
text
string

Text representation of the full name.

If the RelatedPerson is a patient contact but not a Patient on Canvas, this attribute will be populated.

If the RelatedPerson is a Patient on Canvas, this attribute will not be populated; instead the family, given, prefix, and suffix attributes will be provided.

family
string

Family name (often called ‘Surname’).

given
array[string]

Given names (not always ‘first’). Includes middle names.

This repeating element order: Given Names appear in the correct order for presenting the name.

prefix
array[string]

Parts that come before the name.

suffix
array[string]

Parts that come after the name.

telecom
array[json]

Contact details for the individual.

Click to view child attributes
system
string

Supported values are phone, fax, email, pager, url, sms, and other.

value
string

Free text string of the value for this contact point.

use
string

Supported values are home, work, temp, old and mobile.

rank
integer

An integer representing the preferred order of contact points per system.

address
array[json]

Address where the related person can be contacted or visited

Click to view child attributes
use
string

Supported values are home, work, temp and old.

type
string

Supported values are both, physical and postal.

line
array[string]

List of strings. The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.

city
string

String representing the city of the address.

state
string

2 letter state abbreviation of the address.

postalCode
string

The 5 digit postal code of the address.

country
string

The ISO 3166 2 letter country code.

period
json
Click to view child attributes
start
date

Starting date with inclusive boundary

end
date

End date with inclusive boundary, if not ongoing

Responses

200 OK
Request was successful.

Errors

401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/RelatedPerson

RelatedPerson search

Search for RelatedPerson resources.

Query Parameters

_id
string

The identifier of the RelatedPerson.

patient
string

The patient reference associated with the RelatedPerson in the format Patient/a39cafb9d1b445be95a2e2548e12a787.

Response Payload Attributes

resourceType
string

The FHIR Resource name.

type
string

This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .

total
integer

The number of resources that match the search parameter.

link
array[json]

Attributes relevant to pagination, see our Pagination page for more detail.

Click to view child attributes
relation
enum [self|first|next|last]

The relation of the page search

url

The search url for the specific relation

entry
array[json]

The results bundle that lists out each object returned in the search

Click to view child attributes
resource
json

The attributes specific to the resource type, see the Attributes section below

Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the RelatedPerson.

active
boolean

Whether this related person’s record is in active use.

patient
json

The patient this person is related to.

Click to view child attributes
reference
string

The reference string of the patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

Type the reference refers to (e.g. “Patient”).

relationship
array[json]

The nature of the relationship.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/v3-RoleCode
  • Empty string
code
string

The code of the relationship.

Values are nominally from the PatientRelationshipType ValueSet, but custom contact categories can be used as well.

display
string

The display name of the coding.

Values are nominally from the PatientRelationshipType ValueSet, but custom contact categories can be used as well.

name
array[json]

A name associated with the person.

Click to view child attributes
text
string

Text representation of the full name.

If the RelatedPerson is a patient contact but not a Patient on Canvas, this attribute will be populated.

If the RelatedPerson is a Patient on Canvas, this attribute will not be populated; instead the family, given, prefix, and suffix attributes will be provided.

family
string

Family name (often called ‘Surname’).

given
array[string]

Given names (not always ‘first’). Includes middle names.

This repeating element order: Given Names appear in the correct order for presenting the name.

prefix
array[string]

Parts that come before the name.

suffix
array[string]

Parts that come after the name.

telecom
array[json]

Contact details for the individual.

Click to view child attributes
system
string

Supported values are phone, fax, email, pager, url, sms, and other.

value
string

Free text string of the value for this contact point.

use
string

Supported values are home, work, temp, old and mobile.

rank
integer

An integer representing the preferred order of contact points per system.

address
array[json]

Address where the related person can be contacted or visited

Click to view child attributes
use
string

Supported values are home, work, temp and old.

type
string

Supported values are both, physical and postal.

line
array[string]

List of strings. The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.

city
string

String representing the city of the address.

state
string

2 letter state abbreviation of the address.

postalCode
string

The 5 digit postal code of the address.

country
string

The ISO 3166 2 letter country code.

period
json
Click to view child attributes
start
date

Starting date with inclusive boundary

end
date

End date with inclusive boundary, if not ongoing

Responses

200 OK
Request was successful.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  • curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/RelatedPerson/<id>' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

url = "https://fumage-example.canvasmedical.com/RelatedPerson/<id>"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

  • {
  "resourceType": "RelatedPerson",
  "id": "3fcea5ee-8961-43b4-9d47-3e8a2a625e95",
  "active": true,
  "patient": {
    "reference": "Patient/7982b53c2c35427fbb70afceb83145f8",
    "type": "Patient"
  },
  "relationship": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
          "code": "ITWINSIS",
          "display": "identical twin sister"
        }
      ]
    }
  ],
  "name": [
    {
      "family": "Solis",
      "given": [
        "Terry"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5555555555",
      "use": "home",
      "rank": 1
    },
    {
      "system": "email",
      "value": "solisterry@example.net",
      "use": "home",
      "rank": 1
    }
  ],
  "address": [
    {
      "use": "home",
      "type": "both",
      "line": [
        "498 Frank Fields Suite 770"
      ],
      "city": "Taylorbury",
      "state": "RI",
      "postalCode": "90298",
      "country": "us"
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Unknown RelatedPerson resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
      }
    }
  ]
}

  • curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/RelatedPerson?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

url = "https://fumage-example.canvasmedical.com/RelatedPerson?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

  • {
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
    },
    {
      "relation": "first",
      "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
    },
    {
      "relation": "last",
      "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
    }
  ],
  "entry": [
    {
      "resource": {
        "resourceType": "RelatedPerson",
        "id": "3fcea5ee-8961-43b4-9d47-3e8a2a625e95",
        "active": true,
        "patient": {
          "reference": "Patient/7982b53c2c35427fbb70afceb83145f8",
          "type": "Patient"
        },
        "relationship": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                "code": "ITWINSIS",
                "display": "identical twin sister"
              }
            ]
          }
        ],
        "name": [
          {
            "family": "Solis",
            "given": [
              "Terry"
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "5555555555",
            "use": "home",
            "rank": 1
          },
          {
            "system": "email",
            "value": "solisterry@example.net",
            "use": "home",
            "rank": 1
          }
        ],
        "address": [
          {
            "use": "home",
            "type": "both",
            "line": [
              "498 Frank Fields Suite 770"
            ],
            "city": "Taylorbury",
            "state": "RI",
            "postalCode": "90298",
            "country": "us"
          }
        ]
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad request"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}