Practitioner

Last updated: 2 May 2024

A person who is directly or indirectly involved in the provisioning of healthcare.

https://hl7.org/fhir/R4/practitioner.html

To create a new staff member in Canvas, see this Zendesk article.

Related guides:

Patient Messaging

Endpoints

get

/Practitioner/{id}

Practitioner read

Read a Practitioner resource

Path Parameters

id required

string

The unique identifier for the Practitioner

Response Payload Attributes

string

The identifier of the practitioner

identifier

array[json]

An identifier for the person as this agent

name

array[json]

The name(s) associated with the practitioner

address

array[json]

Address(es) of the practitioner entered in Canvas

qualification

array[json]

Certification, licenses, or training pertaining to the provision of care

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

/Practitioner

Practitioner search

Search for Practitioner resources

Query Parameters

_id

string

A Canvas-issued unique identifier

name

string

A search that may match any of the string fields in the name, including family, given, prefix, suffix, and/or text. Partial search is supported. If the practitioner you are looking for is inactive, you will still need to pass include-non-schedulable-practitioners=true.

include-non-schedulable-practitioners

boolean

By default, only schedulable staff are displayed. Passing this parameter as true will return all active staff.

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

string

The identifier of the practitioner

identifier

array[json]

An identifier for the person as this agent

name

array[json]

The name(s) associated with the practitioner

address

array[json]

Address(es) of the practitioner entered in Canvas

qualification

array[json]

Certification, licenses, or training pertaining to the provision of care

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/Practitioner/<id>' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

import requests

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

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

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

print(response.text)

 {
    "resourceType": "Practitioner",
    "id": "e766816672f34a5b866771c773e38f3c",
    "identifier": [
        {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "3554694505"
        }
    ],
    "name": [
        {
            "use": "usual",
            "text": "Youta Priti MD",
            "family": "Priti",
            "given": [
                "Youta"
            ]
        }
    ],
    "address": [
        {
            "use": "work",
            "line": [
                "405 49th St"
            ],
            "city": "Oakland",
            "state": "CA",
            "postalCode": "94609",
            "country": "USA"
        }
    ],
    "qualification": [
          {
            "identifier": [
                {
                    "system": "http://www.mbc.ca.gov/",
                    "value": "A60695"
                }
            ],
            "code": {
                "text": "License"
            },
            "period": {
                "start": "2017-07-11",
                "end": "2019-07-11"
            },
            "issuer": {
                "extension": [
                    {
                        "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                        "valueString": "MEDICAL BOARD OF CALIFORNIA"
                    }
                ],
                "display": "MEDICAL BOARD OF CALIFORNIA"
            }
          }
      ]
  }

{
  "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 Practitioner resource '7d1ce256fcd7408193b0459650937a07'"
            }
        }
    ]
}

curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/Practitioner?name=Magee' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

import requests

url = "https://fumage-example.canvasmedical.com/Practitioner?name=Magee"

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": "/Practitioner?name=Magee&_count=10&_offset=0"
        },
        {
            "relation": "first",
            "url": "/Practitioner?name=Magee&_count=10&_offset=0"
        },
        {
            "relation": "last",
            "url": "/Practitioner?name=Magee&_count=10&_offset=0"
        }
    ],
    "entry": [
        {
            "resource": {
                "resourceType": "Practitioner",
                "id": "3640cd20de8a470aa570a852859ac87e",
                "identifier": [
                    {
                        "system": "http://hl7.org/fhir/sid/us-npi",
                        "value": "2967110133"
                    }
                ],
                "name": [
                    {
                        "use": "usual",
                        "text": "Steven Magee MD",
                        "family": "Magee",
                        "given": [
                            "Steven"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "work",
                        "line": [
                            "405 49th St"
                        ],
                        "city": "Oakland",
                        "state": "CA",
                        "postalCode": "94609",
                        "country": "USA"
                    }
                ],
                "qualification": [
                    {
                        "identifier": [
                            {
                                "system": "http://www.mbc.ca.gov/",
                                "value": "A60695"
                            }
                        ],
                        "code": {
                            "text": "License"
                        },
                        "period": {
                            "start": "2017-07-11",
                            "end": "2019-07-11"
                        },
                        "issuer": {
                            "extension": [
                                {
                                    "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                    "valueString": "MEDICAL BOARD OF CALIFORNIA"
                                }
                            ],
                            "display": "MEDICAL BOARD OF CALIFORNIA"
                        }
                    }
                ]
            }
        }
    ]
}

{
  "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"
      }
    }
  ]
}