Human Services Data API (HSDA) - Taxonomy v1.2

This is the OpenAPI definition for the Human Services Data API (HSDA) v1.2. This is a set of API paths, organized as a separate service, for managing the taxonomy associated with any HSDA inmplementation. It is available as this HTML list or YAML OpenAPI definition, with an accompanying demo site, and link to current Github Issues for support.

Taxonomy
Get Taxonomy /taxonomy/ GET
Reponse Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Add taxonomy /taxonomy/ POST
Request Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Reponse Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Get Taxonomy /taxonomys/{taxonomy_id}/ GET
Path Parameters:
taxonomy_id: The taxonomy id.
Reponse Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Update Taxonomy /taxonomys/{taxonomy_id}/ PUT
Path Parameters:
taxonomy_id: The unique taxonomy id.
Request Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Reponse Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Delete Taxonomy /taxonomys/{taxonomy_id}/ DELETE
Path Parameters:
taxonomy_id: The taxonomy id.
Reponse Body:
id (string) Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.
name (string) The name of this taxonomy term or category.
parent_id (string) If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.
parent_name (string) If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.
vocabulary (string) If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.
Services
Get Services /services/{taxonomy_name}/ GET
Path Parameters:
taxonomy_name: The taxonomy name.
Request Parameters:
query: A query to filter list by (up to provider to determine what to search)
queries: A comma separate list of queries with specific fields.
page: The particular page of results.
per_page: Number of records return per page, up to 100.
sort_by: Which field to sort by.
order: Which order to sort by (asc,desc).
Reponse Body:
id (string) Each service must have a unique identifier.
organization_id (string) The identifier of the organization that provides this service.
program_id (string) The identifier of the program this service is delivered under.
location_id (string) The identifier of the location where this service is delivered.
name (string) The official or public name of the service.
alternate_name (string) Alternative or commonly used name for a service.
description (string) A description of the service.
url (string) URL of the service.
email (string) Email address for the service.
status (string) The current status of the service.
interpretation_services (string) A description of any interpretation services available for accessing this service.
application_process (string) The steps needed to access the service.
wait_time (string) Time a client may expect to wait before receiving a service.
fees (string) Details of any charges for service users to access this service.
accreditations (string) Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.
licenses (string) An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.
Get Services (Complete) /services/complete/{taxonomy_name}/ GET
Path Parameters:
taxonomy_name: The taxonomy name.
Request Parameters:
query: A query to filter list by (up to provider to determine what to search)
queries: A comma separate list of queries with specific fields.
page: The particular page of results.
per_page: Number of records to return per page, up to 100.
sort_by: Which field to sort by.
order: Which order to sort by (asc,desc).
Reponse Body:
id (string) Each service must have a unique identifier.
organization_id (string) The identifier of the organization that provides this service.
program_id (string) The identifier of the program this service is delivered under.
location_id (string) The identifier of the location where this service is delivered.
name (string) The official or public name of the service.
alternate_name (string) Alternative or commonly used name for a service.
description (string) A description of the service.
url (string) URL of the service.
email (string) Email address for the service.
status (string) The current status of the service.
interpretation_services (string) A description of any interpretation services available for accessing this service.
application_process (string) The steps needed to access the service.
wait_time (string) Time a client may expect to wait before receiving a service.
accreditations (string) Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.
licenses (string) An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.
contacts
id (string) - Each contact must have a unique identifier.
organization_id (string) - The identifier of the organization for which this is a contact.
service_id (string) - The identifier of the service for which this is a contact.
service_at_location_id (string) - The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location.
name (string) - The name of the person.
title (string) - The job title of the person.
department (string) - The department that the person is part of.
email (string) - The email address of the person.
eligibility
id (string) - Each entry must have a unique identifier.
service_id (string) - The identifier of the service for which this entry describes the eligibility criteria.
eligibility (string) - The rules or guidelines that determine who can receive the service.
fees
id (string) - Each entry must have a unique identifier.
service_id (string) - The identifier of the service for which this entry describes the costs of service.
fee (string) - A listing of the costs of services, including free ones.
funding
id (string) - Each entry must have a unique identifier.
organization_id (string) - The identifier of the organization for which this entry describes the source of funding.
service_id (string) - The identifier of the service for which this entry describes the source of funding.
source (string) - Source of funds for organization or service.
regular_schedule
id (string) - Each entry must have a unique identifier.
service_id (string) - The identifier of the service for which this is the regular schedule.
location_id (string) - The identifier of the location for which this is the regular schedule.
service_at_location_id (string) - The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.
weekday (string) - The day of the week that this entry relates to.
opens_at (string) - The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.
closes_at (string) - The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.
holiday_schedule
id (string) - Each entry must have a unique identifier.
service_id (string) - The identifier of the service for which this is the holiday schedule.
location_id (string) - The identifier of the location for which this is the holiday schedule.
service_at_location_id (string) - The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.
closed (boolean) - Indicates if a service or location is closed during a public holiday.
opens_at (string) - The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.
closes_at (string) - The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.
start_date (string) - The first day that a service or location is closed during a public or private holiday.
end_date (string) - The last day that a service or location is closed during a public or private holiday.
languages
id (string) - Each language must have a unique identifier.
service_id (string) - The identifier of the service for which the entry describes the languages in which services are delivered.
location_id (string) - The identifier of the location for which the entry describes the languages in which services are delivered.
language (string) - Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes..
payment_accepted
id (string) - Each entry must have a unique identifier.
service_id (string) - The identifier of the services for which the entry describes the accepted payment methods.
payment (string) - The methods of payment accepted for the service.
phones
id (string) - Each entry must have a unique identifier.
location_id (string) - The identifier of the location where this phone number is located.
service_id (string) - The identifier of the service for which this is the phone number.
organization_id (string) - The identifier of the organisation for which this is the phone number.
contact_id (string) - The identifier of the contact for which this is the phone number.
service_at_location_id (string) - The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location.
number (string) - The phone number.
extension (string) - The extension of the phone number.
type (string) - Whether the phone number relates to a fixed or cellular phone.
department (string) - The department for which this is the phone number.
language (string) - A comma separated list of ISO 639-1, or ISO 639-2 [language codes](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities.
description (string) - A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times.
required_documents
id (string) - Each document must have a unique identifier.
service_id (string) - The identifier of the service for which this entry describes the required document.
document (string) - The document required to apply for or receive the service. e.g. Government-issued ID, EU Passport.
service_area
id (string) - Each service area must have a unique identifier.
service_id (string) - The identifier of the service for which this entry describes the service area.
service_area (string) - The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary.
description (string) - A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields.