211HSIS API Docs

Postman collection →

Introduction

This API provides organizations and vendors direct access to 211HSIS Terms.

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token via Taxonomy > APIs > API Keys.

1. Taxonomy Terms

Endpoints for Taxonomy terms

List taxonomy terms.

GET
https://211hsis.org
/api/v1/terms
requires authentication

Top level taxonomies are returned by default, if no parameters supplied.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

search
string

Search terms by a keyword.

Example:
health
code
string

Search terms by code.

Example:
PL-8000.1800-150
parent
string

Pass a term code to get its immediate children.

Example:
PL-8000.1800
filter
string

Return terms included by the given filter ID.

Example:
1339
exclude_filter
string

Return terms that are excluded by the given filter ID.

Example:
1339
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/terms?search=health&code=PL-8000.1800-150&parent=PL-8000.1800&filter=1339&exclude_filter=1339" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "meta": {
        "count": {
            "total": 1,
            "current": 1,
            "perPage": 100
        },
        "page": {
            "total": 1,
            "current": 1,
            "prev": null,
            "next": null
        }
    },
    "data": [
        {
            "code": "B",
            "name": "Basic Needs",
            "parents": [],
            "level": 1,
            "definition": "Programs that furnish survival level resources including food, housing, material goods, transportation and utilities for individuals with low or fixed incomes, people who are homeless, older adults and/or people with disabilities who are otherwise unable to adequately provide for themselves and their families. Also included are related services that are available to the community at large.",
            "created_at": "2023-12-27T14:46:38.304876Z",
            "updated_at": "2023-12-27T14:46:38.304901Z",
            "facet": "Service",
            "has_children": true
        }
    ]
}

Show Taxonomy Term.

GET
https://211hsis.org
/api/v1/terms/{code}
requires authentication

The code is case sensitive.

If you query a term that has been deleted, you will get a 301 redirect to the new term code. We recommend you enable follow redirects in your HTTP client to handle this automatically.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

code
string
required

The code of the taxonomy term.

Example:
PL-8000.1800-150

Query Parameters

filter
string

Return terms included by the given filter ID.

Example:
1339
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/terms/PL-8000.1800-150?filter=1339" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "code": "B",
    "name": "Basic Needs",
    "definition": "Programs that furnish survival level resources including food, housing, material goods, transportation and utilities for individuals with low or fixed incomes, people who are homeless, older adults and/or people with disabilities who are otherwise unable to adequately provide for themselves and their families. Also included are related services that are available to the community at large.",
    "facet": "Service",
    "locale": "en_US",
    "effective_locale": "master",
    "created_at": "1992-03-10T00:00:00.000000Z",
    "updated_at": "2010-03-11T15:11:27.751795Z",
    "comments": null,
    "use_references": [
        "Basic Subsistence"
    ],
    "see_also_references": [],
    "external_terms": [],
    "concepts": [],
    "bibliographic_references": null,
    "parents": [],
    "change_comment": null,
    "old_codes": []
}

2. Related Concepts

Endpoints for Related Concepts

List related concepts.

GET
https://211hsis.org
/api/v1/concepts
requires authentication

Returns all related concepts by default, if no parameters supplied.

Important! When searching related concepts by keyword, pagination is not supported. When searching, you will receive all of the matches as a flat array.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

search
string

Search related concepts by a keyword.

Example:
health
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/concepts?search=health" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "meta": {
      "count": {
        "total": 47,
        "current": 47,
        "perPage": 100
      },
      "page": {
        "total": 1,
        "current": 1,
        "prev": null,
        "next": null
      }
    },
    "data": [
      {
        "code": "AD-900",
        "name": "Advocacy\/Rights Protection"
      },
      {
        "code": "AF-850",
        "name": "After School Programs"
      },
      // 45 more...
    ]
  }

Show concept details.

GET
https://211hsis.org
/api/v1/concepts/{code}
requires authentication

Given the code of a related concept, this endpoint will return the terms under that.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

code
string
required

The code of the related concept.

Example:
AD-900
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/concepts/AD-900" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "code": "AD-900",
    "name": "Advocacy\/Rights Protection",
    "terms": [
      {
        "code": "DF-8000.0200",
        "name": "Accessibility Related Standards\/Legislation Compliance"
      },
      {
        "code": "FP-0500.0100",
        "name": "Administrative Advocacy"
      },
      // .. others
    ]
}

3. External Terms

List external systems.

GET
https://211hsis.org
/api/v1/external-systems
requires authentication

Important! When searching external systems keyword, pagination is not supported. When searching, you will receive all of the matches as a flat array.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

search
string

Search external systems by a keyword.

Example:
iste
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/external-systems?search=iste" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "meta": {
        "count": {
            "total": 6,
            "current": 6,
            "perPage": 100
        },
        "page": {
            "total": 1,
            "current": 1,
            "prev": null,
            "next": null
        }
    },
    "data": [
        {
            "code": "CAN",
            "name": "Canadian Problems/Needs List"
        },
        {
            "code": "ACH",
            "name": "Health Related Social Needs (CMS)"
        },
        {
            "code": "NTE",
            "name": "National Taxonomy of Exempt Entities"
        },
        {
            "code": "NPC",
            "name": "Nonprofit Program Classification System"
        },
        {
            "code": "USA",
            "name": "U.S. Problems/Needs List"
        },
        {
            "code": "UW",
            "name": "UWASIS"
        }
    ]
}

Show external system details.

GET
https://211hsis.org
/api/v1/external-systems/{systemCode}
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

systemCode
string
required

The code of the external system.

Example:
ACH
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/external-systems/ACH" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "code": "ACH",
    "name": "Health Related Social Needs (CMS)",
    "concepts": [
        {
            "code": "A",
            "name": "Living Situation"
        },
        {
            "code": "B",
            "name": "Food"
        },
        {
            "code": "C",
            "name": "Transportation"
        },
        {
            "code": "D",
            "name": "Utilities"
        }
    ]
}

Show external concept details.

GET
https://211hsis.org
/api/v1/external-systems/{systemCode}/concepts/{conceptCode}
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

systemCode
string
required

System code.

Example:
ACH
conceptCode
string
required

Concept code.

Example:
A-01
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/external-systems/ACH/concepts/A-01" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "code": "A-01",
    "name": "Living Situation",
    "system": {
        "code": "ACH",
        "name": "Health Related Social Needs (CMS)"
    },
    "parent": {
        "code": "A",
        "name": "Living Situation"
    },
    "children": [],
    "terms": [
        {
            "code": "BH-0500",
            "name": "At Risk/Homeless Housing Related Assistance Programs",
            "parents": [
                {
                    "name": "Basic Needs",
                    "code": "B"
                },
                {
                    "name": "Housing/Shelter",
                    "code": "BH"
                }
            ],
            "level": 3,
            "definition": "Programs authorized under federal or state legislation or local government initiatives that provide financial assistance and supportive services for individuals and/or families who are homeless or at risk for homelessness. Included are prevention programs that help people at imminent risk for homelessness preserve current housing or secure alternative housing; diversion programs that help people actively seeking shelter to identify and access viable alternatives including shared housing arrangements and transitional housing/shelter; and rapid re-housing programs that help people who are already homeless move as quickly as possible into permanent housing. Services may include case management, rental deposits, rent assistance, utility deposits, housing search assistance, moving expenses, expenses related to non-shelter temporary housing in situations where permanent housing has been secured but is currently unavailable, and other costs the family may incur in the process of acquiring or maintaining housing. Allowable activities, eligibility criteria and other requirements vary depending on the jurisdiction, the funding source and the focus of the program.",
            "created_at": "2023-12-27T15:14:51.239579Z",
            "updated_at": "2023-12-27T15:14:51.239599Z",
            "facet": "Service",
            "has_children": true
        }
    ]
}

List external terms.

GET
https://211hsis.org
/api/v1/external-terms
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

search
string

Search external terms by a keyword.

Example:
health
system_code
string

Search external terms by system code.

Example:
ACH
first_level
string

It lists only first level external terms.

Example:
1
exclude_first_level
string

It lists external terms except first level.

Example:
1
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/external-terms?search=health&system_code=ACH&first_level=1&exclude_first_level=1" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers 
                                                            cache-control
                                                            : no-cache, private
                                                                                                                    content-type
                                                            : application/json
                                                                                                                    content-language
                                                            : en
                                                         
{
    "meta": {
        "count": {
            "total": 0,
            "current": 0,
            "perPage": 100
        },
        "page": {
            "total": 1,
            "current": 1,
            "prev": null,
            "next": null
        }
    },
    "data": []
}

4. Recent Changes

Get Recent Changes

GET
https://211hsis.org
/api/v1/recent-changes
requires authentication

As the taxonomy evolves, new terms are added, existing terms are modified, and some terms are removed. This endpoint allows you to get a chronological list of changes that have been made to the taxonomy.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

code
string

Filter changes by term code

Example:
PL-8000.1800-150
from
string

List changes starting from date (unix timestamp)

Example:
1588291200
to
string

List changes up to this date (unix timestamp)

Example:
1588291200
type
string

Comma-seperated of change types to include.

Example:
NEW,CODE CHANGE,CHANGE,DELETION
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/recent-changes?code=PL-8000.1800-150&from=1588291200&to=1588291200&type=NEW%2CCODE+CHANGE%2CCHANGE%2CDELETION" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "meta": {
        "count": {
            "total": 13206,
            "current": 100,
            "perPage": 100
        },
        "page": {
            "total": 133,
            "current": 1,
            "prev": null,
            "next": "https://taxonomy.test/api/v1/recent-changes?page=2"
        }
    },
    "data": [
        {
            "id": 17603,
            "code": "RX-8470.1900-180.25",
            "new_code": "RX-8470.1900-180.25",
            "locale": "en_US",
            "name": "General Drug Related Harm Reduction Supplies",
            "description": "Programs that distribute an assortment of supplies that help prevent the transmission of HIV/AIDS, hepatitis B and C, and other blood-borne infectious diseases by providing new, sterile and single use equipment and biohazard containers for safe disposal, in order to reduce the spread of these diseases. Supplies provided may vary per program, and can include safe injection supplies (needles with syringes, needle tips, syringes, sterile water vials, cookers, acidifiers, alcohol swabs, tourniquets), safe inhalation supplies (pipes, stems, screens, mouth pieces, push sticks, foils), drug testing, and antidotes to reverse an overdose from opioids. Also included are supplies for safe hormone injection for trans, gender diverse and two-spirited individuals who face unique barriers and inequitable access to gender-affirming health care services. The distribution of supplies is part of a comprehensive public health disease prevention strategy with the goal to reduce re-using and sharing drug use equipment. See Also Fentanyl Test Strip Distribution (RX-8470.1900-180.20)\nInhalation Supplies (RX-8470.1900-180.33)\nNeedle Exchange and Injection Supplies (RX-8470.1900-180.60)\nOpioid Antidote Distribution (RX-8470.1900-180.65). = Harm Reduction Distribution Programs",
            "type": "NEW",
            "date": "2023-07-19T19:39:56.848086Z"
        },
        {
            "id": 17607,
            "code": "RX-8470.1900-610",
            "new_code": "RX-8470.1900-180.60",
            "locale": "en_US",
            "name": "Needle Exchange/Distribution Programs",
            "description": "Code change to RX-8470.1900-180.60. Term name change to Needle Exchange and Injection Supplies. See Also General Drug Related Harm Reduction Supplies (RX-8470.1900-180.25). = Bleach Kits = Harm Reduction Supplies for Hormone Injection = Hormone Injection Toolkits = Hypodermic Needle Supplies and Exchange = Needle Exchange and Injection Distribution = Needle Exchange/Distribution Programs = NEP =\nSafe Drug Injection Supplies = Safer Hormone Injection Supplies =\nSafe Sharps Exchange/Distribution Programs = Syringe Services Programs = SSP = Injection Equipment Distribution",
            "type": "CODE CHANGE",
            "date": "2023-07-19T17:28:09.957343Z"
        }
    ]
}

5. Filters

List filters

GET
https://211hsis.org
/api/v1/filters
requires authentication

Filters allow you to refine taxonomy by excluding terms that are not relevant to your organization. Once you create a filter, you can use it to filter taxonomy terms in the /terms endpoint.

This endpoint will return all filters that are visible to you. This will include:

  1. 1. Your own filters
  2. 2. Community filters
  3. 3. Filters created and shared by 211 HSIS

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/filters" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "meta": {
        "count": {
            "total": 1,
            "current": 1,
            "perPage": 10
        },
        "page": {
            "total": 1,
            "current": 1,
            "prev": null,
            "next": null
        }
    },
    "data": [
        {
            "id": 1,
            "name": "My Example Filter",
            "description": null,
            "contact_name": null,
            "contact_phone": null,
            "owner_id": 1,
            "type": "private",
            "excluded_terms": [
                {
                    "code": "B",
                    "children_only": false
                }
            ],
            "updated_at": "2023-12-26T16:28:02.000000Z",
            "approved_at": null,
            "is_pending_approval": false,
            "owner": {
                "id": 1,
                "firstname": "John",
                "lastname": "Doe",
                "organization": "211 HSIS"
            }
        }
    ]
}

Create a new filter.

POST
https://211hsis.org
/api/v1/filters
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://211hsis.org/api/v1/filters" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"My Filter\",
    \"description\": \"This is a filter I created to exclude terms that are not relevant to my organization.\",
    \"contact_name\": \"John Doe\",
    \"contact_phone\": \"123-456-7890\",
    \"type\": \"private\"
}"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}

Show filter

GET
https://211hsis.org
/api/v1/filters/{filter}
requires authentication

Retrieve the details of a filter.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter
string
required

Filter ID

Example:
quaerat
Example request: 
curl --request GET \
    --get "https://211hsis.org/api/v1/filters/quaerat" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}

Exclude terms in a filter.

PATCH
https://211hsis.org
/api/v1/filters/{filter_id}/exclude
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter_id
integer
required

The ID of the filter.

Example:
3
filter
string
required

Filter ID

Example:
1

Body Parameters

Example request: 
curl --request PATCH \
    "https://211hsis.org/api/v1/filters/3/exclude" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"terms\": [
        {
            \"code\": \"BD\",
            \"children_only\": false
        }
    ]
}"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}

Remove exclusions of terms in a filter.

PATCH
https://211hsis.org
/api/v1/filters/{filter_id}/remove-exclusion
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter_id
integer
required

The ID of the filter.

Example:
3
filter
string
required

Filter ID

Example:
1

Body Parameters

Example request: 
curl --request PATCH \
    "https://211hsis.org/api/v1/filters/3/remove-exclusion" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"terms\": [
        {
            \"code\": \"BD\",
            \"children_only\": false
        }
    ]
}"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}

Update a filter.

PATCH
https://211hsis.org
/api/v1/filters/{filter_id}
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter_id
integer
required

The ID of the filter.

Example:
3
filter
string
required

Filter ID

Example:
1

Body Parameters

Example request: 
curl --request PATCH \
    "https://211hsis.org/api/v1/filters/3" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"My Filter\",
    \"description\": \"This is a filter I created to exclude terms that are not relevant to my organization.\",
    \"contact_name\": \"John Doe\",
    \"contact_phone\": \"123-456-7890\",
    \"type\": \"private\"
}"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}

Delete a filter.

DELETE
https://211hsis.org
/api/v1/filters/{filter_id}
requires authentication

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter_id
integer
required

The ID of the filter.

Example:
3
filter
string
required

Filter ID

Example:
1
Example request: 
curl --request DELETE \
    "https://211hsis.org/api/v1/filters/3" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{}

Clone a filter

POST
https://211hsis.org
/api/v1/filters/{filter}/clone
requires authentication

Create a 1-1 copy of another filter. The new filter will be private and owned by you.

Headers

Authorization
Example:
Bearer {token}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

filter
string
required

Filter ID

Example:
1

Body Parameters

Example request: 
curl --request POST \
    "https://211hsis.org/api/v1/filters/1/clone" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Copied Filter\"
}"
Example response:
{
    "id": 5,
    "name": "My Filter",
    "description": "This is a filter I created to exclude terms that are not relevant to my organization.",
    "contact_name": "John Doe",
    "contact_phone": "123-456-7890",
    "owner_id": 1,
    "type": "private",
    "excluded_terms": [],
    "updated_at": "2023-12-27T15:26:42.000000Z",
    "approved_at": null,
    "is_pending_approval": false,
    "owner": {
        "id": 1,
        "firstname": "John",
        "lastname": "Doe",
        "organization": "211 HSIS"
    }
}