Organization

A formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, payer/insurer, etc.

http://hl7.org/fhir/us/core/STU3.1.1/StructureDefinition-us-core-organization.html

Organizations come from three different Canvas data types: Organizations, Vendors, and Insurers. You can manage these resources in Canvas Settings. FHIR Organizations created by Insurers in Canvas are useful in the FHIR Coverage payor attribute.

get
/Organization/{id}

Organization read

Read an Organization resource.

Path Parameters

id required
string
The unique identifier for the Organization

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the Organization.

identifier
array[json]

Identifies this organization across multiple systems.

When relevant, group NPI values, taxonomy ids, and tax ids will be found for relevant organizations. Identifiers for vendors and transactors, such as insurance payor values, are not yet supported.

Click to view child attributes
type
array

Description of identifier.

Currently only type will appear for Organizations with a Tax ID.

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/v2-0203
code
string

The code of the clinical status.

Value Options Supported:
  • TAX
display
string

The display name of the coding.

Value Options Supported:
  • Tax ID number
system
string

The namespace for the identifier value.

Value Options Supported:
  • urn:oid:2.16.840.1.113883.4.4 (for Tax ID)
  • http://hl7.org/fhir/sid/us-npi (for NPI)
value
string

The value that is unique.

active
boolean

Whether the organization’s record is still in active use.

name
string

Name used for the organization.

telecom
array[json]

A contact detail for the organization (phone / email / fax).

Click to view child attributes
system
enum [ phone | fax | email | pager | other ]

Telecommunications form for contact point - what communications system is required to make use of the contact.

value
string

The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).

use
enum [ work | temp | old | mobile ]

Identifies the purpose for the contact point.

address
array[json]

An address for the organization. This will include both physical and billing addresses, when available.

Click to view child attributes
use
enum [ work | temp | old | billing ]

Defines the purpose of this address.

type
enum [ both | physical | postal ]

Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses).

line
array[string]

This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.

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

The name of the city, town, suburb, village or other community or delivery center.

state
string

Two-letter state abbreviation of the address.

postalCode
string

The 5-digit postal code of the address.

country
string

Specifies the country in which the organization’s address is located.

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.

Query Parameters

_id
string

The identifier of the Organization

address
string

A server defined search that may match any of the string fields in the Address, including line, city, state, and/or postalCode

name
string

A portion of the organization’s name

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 Organization.

identifier
array[json]

Identifies this organization across multiple systems.

When relevant, group NPI values, taxonomy ids, and tax ids will be found for relevant organizations. Identifiers for vendors and transactors, such as insurance payor values, are not yet supported.

Click to view child attributes
type
array

Description of identifier.

Currently only type will appear for Organizations with a Tax ID.

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/v2-0203
code
string

The code of the clinical status.

Value Options Supported:
  • TAX
display
string

The display name of the coding.

Value Options Supported:
  • Tax ID number
system
string

The namespace for the identifier value.

Value Options Supported:
  • urn:oid:2.16.840.1.113883.4.4 (for Tax ID)
  • http://hl7.org/fhir/sid/us-npi (for NPI)
value
string

The value that is unique.

active
boolean

Whether the organization’s record is still in active use.

name
string

Name used for the organization.

telecom
array[json]

A contact detail for the organization (phone / email / fax).

Click to view child attributes
system
enum [ phone | fax | email | pager | other ]

Telecommunications form for contact point - what communications system is required to make use of the contact.

value
string

The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).

use
enum [ work | temp | old | mobile ]

Identifies the purpose for the contact point.

address
array[json]

An address for the organization. This will include both physical and billing addresses, when available.

Click to view child attributes
use
enum [ work | temp | old | billing ]

Defines the purpose of this address.

type
enum [ both | physical | postal ]

Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses).

line
array[string]

This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.

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

The name of the city, town, suburb, village or other community or delivery center.

state
string

Two-letter state abbreviation of the address.

postalCode
string

The 5-digit postal code of the address.

country
string

Specifies the country in which the organization’s address is located.

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/Organization/<id>' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Organization/<id>"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>"
    }
    
    response = requests.get(url, headers=headers)
    
    print(response.text)
    
  • {
        "resourceType": "Organization",
        "id": "192cf534-fc40-4c68-a233-062807338635",
        "identifier": [
            {
                "system": "http://hl7.org/fhir/sid/us-npi",
                "value": "1111111112"
            },
            {
                "system": "http://nucc.org/provider-taxonomy",
                "value": "207Q00000X"
            },
            {
                "type": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                            "code": "TAX",
                            "display": "Tax ID number"
                        }
                    ]
                },
                "system": "urn:oid:2.16.840.1.113883.4.4",
                "value": "123456789"
            }
        ],
        "active": true,
        "name": "Canvas Training Organization",
        "telecom": [
            {
                "system": "fax",
                "value": "2314217892",
                "use": "work"
            },
            {
                "system": "email",
                "value": "example@example.com",
                "use": "work"
            },
            {
                "system": "phone",
                "value": "9567768088",
                "use": "work"
            }
        ],
        "address": [
            {
                "use": "work",
                "type": "both",
                "line": [
                    "3300 Washtenaw Avenue, Suite 227"
                ],
                "city": "Amherst",
                "state": "MA",
                "postalCode": "01002",
                "country": "United States"
            },
            {
                "use": "billing",
                "type": "both",
                "line": [
                    "1 Billing Lane"
                ],
                "city": "NY",
                "state": "NY",
                "postalCode": "11111",
                "country": "USA"
            }
        ]
    }
    
  • {
      "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 Organization resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
          }
        }
      ]
    }
    
  • curl --request GET \
         --url 'https://fumage-example.canvasmedical.com/Organization?name=Canvas' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Organization?name=Canvas"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>"
    }
    
    response = requests.get(url, headers=headers)
    
    print(response.text)
    
  • {
        "resourceType": "Bundle",
        "type": "searchset",
        "total": 2,
        "link": [
            {
                "relation": "self",
                "url": "/Organization?name=Canvas&_count=10&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Organization?name=Canvas&_count=10&_offset=0"
            },
            {
                "relation": "last",
                "url": "/Organization?name=Canvas&_count=10&_offset=0"
            }
        ],
        "entry": [
            {
                "resource": {
                    "resourceType": "Organization",
                    "id": "00000000-0000-0000-0002-000000000000",
                    "active": true,
                    "name": "Canvas Medical",
                    "telecom": [
                        {
                            "system": "phone",
                            "value": "8003701416",
                            "use": "work"
                        },
                        {
                            "system": "email",
                            "value": "example@canvasmedical.com",
                            "use": "work"
                        }
                    ],
                    "address": [
                        {
                            "use": "work",
                            "type": "both",
                            "line": [
                                "2037 Irving Street",
                                "Suite 228"
                            ],
                            "city": "San Francisco",
                            "state": "CA",
                            "postalCode": "94122"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Organization",
                    "id": "192cf534-fc40-4c68-a233-062807338635",
                    "identifier": [
                        {
                            "system": "http://hl7.org/fhir/sid/us-npi",
                            "value": "1111111112"
                        },
                        {
                            "system": "http://nucc.org/provider-taxonomy",
                            "value": "207Q00000X"
                        },
                        {
                            "type": {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                        "code": "TAX",
                                        "display": "Tax ID number"
                                    }
                                ]
                            },
                            "system": "urn:oid:2.16.840.1.113883.4.4",
                            "value": "123456789"
                        }
                    ],
                    "active": true,
                    "name": "Canvas Training Organization",
                    "telecom": [
                        {
                            "system": "fax",
                            "value": "2314217892",
                            "use": "work"
                        },
                        {
                            "system": "email",
                            "value": "example@example.com",
                            "use": "work"
                        },
                        {
                            "system": "phone",
                            "value": "9567768088",
                            "use": "work"
                        }
                    ],
                    "address": [
                        {
                            "use": "work",
                            "type": "both",
                            "line": [
                                "3300 Washtenaw Avenue, Suite 227"
                            ],
                            "city": "Amherst",
                            "state": "MA",
                            "postalCode": "01002",
                            "country": "United States"
                        },
                        {
                            "use": "billing",
                            "type": "both",
                            "line": [
                                "1 Billing Lane"
                            ],
                            "city": "NY",
                            "state": "NY",
                            "postalCode": "11111",
                            "country": "USA"
                        }
                    ]
                }
            }
        ]
    }
    
  • {
      "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"
          }
        }
      ]
    }