US Address Enrichment API
Returns up to 350 property attributes for a US address, including property characteristics, estimated value, ownership data, and neighborhood demographics to enrich address records.
OpenAPI Specification
openapi: 3.0.1
info:
title: us-enrichment-api
version: '1.0'
description: 'This page describes how to retrieve data from various different datasets using the Smarty US Address Enrichment API.'
contact:
url: 'https://www.smarty.com/contact/support'
email: [email protected]
name: Smarty Support
termsOfService: 'https://www.smarty.com/legal/terms-of-service'
license:
url: 'https://www.smarty.com/legal/terms-of-service'
name: Smarty License
servers:
- url: 'https://us-enrichment.api.smarty.com'
externalDocs:
description: "Extensive documentation for the US Address Enrichment API"
url: https://www.smarty.com/docs/cloud/us-address-enrichment-api
paths:
'/lookup/{smartykey}/property':
get:
operationId: get-lookup-smartykey-property
tags:
- us-enrichment
summary: Property Lookup by Smartykey
description: 'Contains all property data attributes including tax assessor and recorder data. Recorder data will be last available financial transaction for the property. When requesting the financial feature, the result will contain historical financial data pertaining to the property and property owner.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/smartykey'
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
responses:
'200':
$ref: '#/components/responses/PropertyResponseSmartyKey'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/search/property':
get:
operationId: get-lookup-property
tags:
- us-enrichment
summary: Property Lookup by Search Fields
description: 'Contains all property data attributes including tax assessor and recorder data. Recorder data will be last available financial transaction for the property. When requesting the financial feature, the result will contain historical financial data pertaining to the property and property owner.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
- $ref: '#/components/parameters/freeform'
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/zipcode'
responses:
'200':
$ref: '#/components/responses/PropertyResponseSearch'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/{smarykey}/geo-reference/{dataset?}':
get:
operationId: get-lookup-smartykey-geo
tags:
- us-enrichment
summary: US Census Block and Tract Lookup by Smartykey
description: 'The Census Block and Tract Data product provides useful geographic data for geocoded addresses, such as census block id. Request legacy data, such as the 2010 and 2020 census, by specifying a data subset of 2010 or 2020. For example: To return 2010 census data, specify geo-reference/2010. To request the latest census information available, simply specify geo-reference with no trailing subset. The census version will be returned in the data_set_version property in the response.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/smartykey'
- $ref: '#/components/parameters/dataset'
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
responses:
'200':
$ref: '#/components/responses/CensusBlockAndTractResponseSmartyKey'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/search/geo-reference/{dataset?}':
get:
operationId: get-lookup-geo
tags:
- us-enrichment
summary: US Census Block and Tract Data Lookup by Search Fields
description: 'The Census Block and Tract Data product provides useful geographic data for geocoded addresses, such as census block id. Request legacy data, such as the 2010 and 2020 census, by specifying a data subset of 2010 or 2020. For example: To return 2010 census data, specify geo-reference/2010. To request the latest census information available, simply specify geo-reference with no trailing subset. The census version will be returned in the data_set_version property in the response.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/dataset'
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
- $ref: '#/components/parameters/freeform'
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/zipcode'
responses:
'200':
$ref: '#/components/responses/CensusBlockAndTractResponseSearch'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/{smartykey}/secondary':
get:
operationId: get-lookup-smartykey-secondary
tags:
- us-enrichment
summary: US Secondary Data Lookup by Smartykey
description: 'The secondary data product returns all secondaries and aliases associated with a SmartyKey. The SmartyKey can be that of the root address, any of the aliases, or any of the secondaries. Each will return the same related data.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/smartykey'
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
responses:
'200':
$ref: '#/components/responses/SecondaryResponseSmartyKey'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/search/secondary':
get:
operationId: get-lookup-secondary
tags:
- us-enrichment
summary: US Secondary Data Lookup by Search Fields
description: 'The secondary data product returns all secondaries and aliases associated with a SmartyKey. Each will return the same related data.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
- $ref: '#/components/parameters/freeform'
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/zipcode'
responses:
'200':
$ref: '#/components/responses/SecondaryResponseSearch'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/{smartykey}/secondary/count':
get:
operationId: get-lookup-smartykey-secondary-count
tags:
- us-enrichment
summary: US Secondary Data Lookup by Smartykey
description: 'The secondary data product returns all secondaries and aliases associated with a SmartyKey. The SmartyKey can be that of the root address, any of the aliases, or any of the secondaries. Each will return the same related data. The count subset only returns the number of secondaries associated with the SmartyKey. Detailed data is not returned.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/smartykey'
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
responses:
'200':
$ref: '#/components/responses/SecondaryCountResponseSmartyKey'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'/lookup/search/secondary/count':
get:
operationId: get-lookup-secondary-count
tags:
- us-enrichment
summary: US Secondary Data Lookup by Search Fields
description: 'The secondary data product returns all secondaries and aliases associated with a SmartyKey. Each will return the same related data. The count subset only returns the number of secondaries associated with the SmartyKey. Detailed data is not returned.'
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
parameters:
- $ref: '#/components/parameters/content-type'
- $ref: '#/components/parameters/etag'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/features'
- $ref: '#/components/parameters/freeform'
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/zipcode'
responses:
'200':
$ref: '#/components/responses/SecondaryCountResponseSearch'
'304':
$ref: '#/components/responses/NotModified'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'413':
$ref: '#/components/responses/RequestTooLarge'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- name: us-enrichment
components:
parameters:
smartykey:
name: smartykey
in: path
required: true
schema:
type: string
description: "The unique id associated with the address you are looking for."
dataset:
name: dataset
in: path
required: false
schema:
type: string
enum: [ '2010','2020']
content-type:
name: Content-type
in: header
schema:
type: string
example: 'application/json'
description: 'The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner.'
etag:
name: ETag
in: header
schema:
type: string
example: 'AUHQQBIPBQDAYAA'
description: 'The ETag header provides the ability to check if a record has been updated since the last query. Every query to the API will return an ETag header which represents a hash of the record in the response. This value may be stored and used in subsequent queries for that same record. If the record data has NOT been updated since the last query, it will return a 304 (Not Modified) and the client will not be charged for the query. (The 304 response does not contain a body.) If the record data HAS been updated, the latest version of the record will be returned along with a new ETag value. Important: Only the latest ETag value is valid for each record. This feature is NOT designed to retrieve past record versions. Also note that the ETag value will change if ANY data in the record has been updated, regardless of which attributes are requested using the include and exclude parameters.'
include:
name: include
in: query
schema:
type: string
description: 'List of attributes that are allowed to be included in the response. This list can include Group names and Attribute names separated by commas. All values must be lowercase. If the record in the response does not have a value for that attribute, it will not be included in the response.'
exclude:
name: exclude
in: query
schema:
type: string
description: 'List of attributes that are not allowed to be included in the response. This list can include Group names and Attribute names separated by commas. All values must be lowercase.'
features:
name: features
in: query
schema:
type: string
description: 'A comma-separated list of features. These may require a special plan that allows the feature to be used. EXAMPLE: Feature Value: financial; Description: Return the financial_history attribute. This is applicalbe only to property requests. Default: 128'
freeform:
name: freeform
in: query
schema:
type: string
description: 'A full address.'
street:
name: street
in: query
schema:
type: string
description: 'The street line of the address, or the entire address. You may also need to provide values for other component search fields.'
city:
name: city
in: query
schema:
type: string
description: 'The city name or a city, state, and ZIP Code combined. You may also need to provide values for other component search fields.'
state:
name: state
in: query
schema:
type: string
description: 'The state name or abbreviation. You may also need to provide values for other component search fields.'
zipcode:
name: zipcode
in: query
schema:
type: string
description: 'The ZIP Code. You may also need to provide values for other component search fields.'
schemas:
PropertyResponseSmartyKey:
properties:
smarty_key:
type: string
data_set_name:
type: string
data_subset_name:
type: string
attributes:
oneOf:
- allOf:
- $ref: '#/components/schemas/GroupStructuralAttributes'
- $ref: '#/components/schemas/GroupLocationAttributes'
- $ref: '#/components/schemas/GroupFinancialAttributes'
PropertyResponseSearch:
properties:
smarty_key:
type: string
data_set_name:
type: string
data_subset_name:
type: string
matched_address:
$ref: '#/components/schemas/MatchedAddress'
attributes:
oneOf:
- allOf:
- $ref: '#/components/schemas/GroupStructuralAttributes'
- $ref: '#/components/schemas/GroupLocationAttributes'
- $ref: '#/components/schemas/GroupFinancialAttributes'
CensusBlockAndTractResponseSmartyKey:
properties:
smarty_key:
type: string
data_set_name:
type: string
data_set_version:
type: string
attributes:
type: object
properties:
census_block:
$ref: '#/components/schemas/CensusBlock'
census_county_division:
$ref: '#/components/schemas/CensusCountyDivision'
census_tract:
$ref: '#/components/schemas/CensusTract'
core_based_stat_area:
$ref: '#/components/schemas/CoreBasedStatArea'
place:
$ref: '#/components/schemas/Place'
CensusBlockAndTractResponseSearch:
properties:
smarty_key:
type: string
data_set_name:
type: string
data_set_version:
type: string
matched_address:
$ref: '#/components/schemas/MatchedAddress'
attributes:
type: object
properties:
census_block:
$ref: '#/components/schemas/CensusBlock'
census_county_division:
$ref: '#/components/schemas/CensusCountyDivision'
census_tract:
$ref: '#/components/schemas/CensusTract'
core_based_stat_area:
$ref: '#/components/schemas/CoreBasedStatArea'
place:
$ref: '#/components/schemas/Place'
SecondaryResponseSmartyKey:
type: object
properties:
smarty_key:
type: string
root_address:
$ref: '#/components/schemas/RootAddress'
aliases:
type: array
items:
$ref: '#/components/schemas/Alias'
secondaries:
type: array
items:
$ref: '#/components/schemas/Secondaries'
SecondaryResponseSearch:
type: object
properties:
smarty_key:
type: string
matched_address:
$ref: '#/components/schemas/MatchedAddress'
root_address:
$ref: '#/components/schemas/RootAddress'
aliases:
type: array
items:
$ref: '#/components/schemas/Alias'
secondaries:
type: array
items:
$ref: '#/components/schemas/Secondaries'
SecondaryCountResponseSmartyKey:
type: object
properties:
smarty_key:
type: string
count:
type: integer
SecondaryCountResponseSearch:
type: object
properties:
smarty_key:
type: string
matched_address:
$ref: '#/components/schemas/MatchedAddress'
count:
type: integer
CensusBlock:
type: object
description: 'An id of up to 15 characters that identifies a geographical area for statistical analysis.'
properties:
accuracy:
type: string
description: 'Represents the accuracy of the geocode associated with the SmartyKey which was used to find the block. Values are block, tract, or county.'
geoid:
type: string
description: |-
The census geoid can have different meanings based on the accuracy field.
If geocode accuracy is parcel or rooftop, the id is the 15 character block id.
If geocode accuracy is zip9, the id is the census tract id. (first 11 digits of block id)
If geocode accuracy is less than zip9, the id is the county FIPS. (first 5 digits of block id)
CensusCountyDivision:
type: object
description: 'The county subdivision identifier and name (equivalent to townships).'
properties:
accuracy:
type: string
description: 'Represents the accuracy of the geocode associated with the SmartyKey. Less than Zip9 accuracy will be inferred. Otherwise, it will be exact.'
code:
type: string
description: 'The 10-digit census id code of the CCD.'
name:
type: string
description: 'The name of the census county division.'
CensusTract:
type: string
description: 'Geographic entities within counties (or the statistical equivalent of counties).'
properties:
code:
type: string
description: 'Census tracts within a county are identified by a 4-digit basic code between 0001 and 9999, and may have a 2-digit suffix ranging from .01 to .98; (e.g. 6059.02)'
CoreBasedStatArea:
type: object
description: 'Refers collectively to metropolitan statistical areas and micropolitan statistical areas. CBSAs consist of the county or counties (or equivalent entities) associated with at least one core (urban area) with a population of at least 10,000, plus adjacent counties having a high degree of social and economic integration with the core as measured through commuting ties.'
properties:
code:
type: string
description: 'A 5-digit unique id of the CBSA (e.g. 39340)'
name:
type: string
description: 'The name of the CBSA (e.g. Provo-Orem, UT)'
Place:
type: object
description: 'The Bureau of the Census defines a place as a concentration of population. It consists of a geographical boundary.'
properties:
accuracy:
type: string
description: 'Represents the accuracy of the geocode associated with the SmartyKey. Less than Zip9 accuracy will be inferred. Otherwise, it will be exact.'
code:
type: string
description: 'A 7-digit code that identifies the place. The first 2 digits identify the state. The last 5 identify the place within the state.'
name:
type: string
description: 'The name of the place boundary.'
type:
type: string
description: 'Indicates if the Census Place is incorporated or unincorporated.'
GroupFinancialAttributes:
type: object
description: "Financial attributes in the Financial Dataset records."
properties:
assessed_improvement_percent:
type: string
assessed_improvement_value:
type: string
assessed_land_value:
type: string
assessed_value:
type: string
assessor_last_update:
type: string
assessor_taxroll_update:
type: string
code_title_company:
type: string
company_flag:
type: string
contact_city:
type: string
contact_crrt:
type: string
contact_full_address:
type: string
contact_house_number:
type: string
contact_mail_info_format:
type: string
contact_mailing_county:
type: string
contact_mailing_fips:
type: string
contact_post_direction:
type: string
contact_pre_direction:
type: string
contact_state:
type: string
contact_street_name:
type: string
contact_suffix:
type: string
contact_unit_designator:
type: string
contact_value:
type: string
contact_zip:
type: string
contact_zip4:
type: string
deed_document_page:
type: string
deed_document_book:
type: string
deed_document_number:
type: string
deed_owner_first_name:
type: string
deed_owner_first_name2:
type: string
deed_owner_first_name3:
type: string
deed_owner_first_name4:
type: string
deed_owner_full_name:
type: string
deed_owner_full_name2:
type: string
deed_owner_full_name3:
type: string
deed_owner_full_name4:
type: string
deed_owner_last_name:
type: string
deed_owner_last_name2:
type: string
deed_owner_last_name3:
type: string
deed_owner_last_name4:
type: string
deed_owner_middle_name:
type: string
deed_owner_middle_name2:
type: string
deed_owner_middle_name3:
type: string
deed_owner_middle_name4:
type: string
deed_owner_suffix:
type: string
deed_owner_suffix2:
type: string
deed_owner_suffix3:
type: string
deed_owner_suffix4:
type: string
deed_sale_date:
type: string
deed_sale_price:
type: string
deed_transaction_id:
type: string
disabled_tax_exemption:
type: string
financial_history:
$ref: '#/components/schemas/FinancialHistoryEntry'
first_name:
type: string
first_name_2:
type: string
first_name_3:
type: string
first_name_4:
type: string
homeowner_tax_exemption:
type: string
instrument_date:
type: string
interest_rate:
type: string
interest_rate_type_2:
type: string
last_name:
type: string
last_name_2:
type: string
last_name_3:
type: string
last_name_4:
type: string
lender_address:
type: string
lender_address_2:
type: string
lender_city:
type: string
lender_city_2:
type: string
lender_code_2:
type: string
lender_first_name:
type: string
lender_first_name_2:
type: string
lender_last_name:
type: string
lender_last_name_2:
type: string
lender_name:
type: string
lender_name_2:
type: string
lender_seller_carry_back:
type: string
lender_seller_carry_back_2:
type: string
lender_state:
type: string
lender_state_2:
type: string
lender_zip:
type: string
lender_zip_2:
type: string
lender_zip_extended:
type: string
lender_zip_extended_2:
type: string
loan_amount:
type: string
market_improvement_percent:
type: string
market_improvement_value:
type: string
market_land_value:
type: string
market_value_year:
type: string
middle_name:
type: string
middle_name_2:
type: string
middle_name_3:
type: string
middle_name_4:
type: string
mortgage_amount_2:
type: string
mortgage_due_date:
type: string
mortgage_due_date_2:
type: string
mortgage_interest_type:
type: string
mortgage_lender_code:
type: string
mortgage_start_date:
type: string
mortgage_start_date_2:
type: string
mortgage_term:
type: string
mortgage_term_2:
type: string
mortgage_term_type:
type: string
mortgage_term_type_2:
type: string
mortgage_type:
type: string
mortgage_type_2:
type: string
mortgage_rate_2:
type: string
multi_parcel_flag:
type: string
name_title_company:
type: string
other_tax_exemption:
type: string
owner_full_name:
type: string
owner_full_name_2:
type: string
owner_full_name_3:
type: string
owner_full_name_4:
type: string
owner_occupancy_status:
type: string
ownership_transfer_date:
type: string
ownership_transfer_doc_number:
type: string
ownership_transfer_transaction_id:
type: string
ownership_type:
type: string
ownership_type_2:
type: string
ownership_vesting_relation_code:
type: string
previous_assessed_value:
type: string
prior_sale_amount:
type: string
prior_sale_date:
type: string
sale_amount:
type: string
sale_date:
type: string
sale_price:
type: string
senior_tax_exemption:
type: string
suffix:
type: string
suffix_2:
type: string
suffix_3:
type: string
suffix_4:
type: string
tax_assess_year:
type: string
tax_billed_amount:
type: string
tax_delinquent_year:
type: string
tax_fiscal_year:
type: string
tax_rate_area:
type: string
total_market_value:
type: string
trust_description:
type: string
veteran_tax_exemption:
type: string
widow_tax_exemption:
type: string
GroupLocationAttributes:
type: object
description: "Location attributes in the Principal Dataset records."
properties:
block1:
type: string
block2:
type: string
carrier_route_code:
type: string
cbsa_code:
type: string
cbsa_name:
type: string
census_block:
type: string
census_block_group:
type: string
census_fips_place_code:
type: string
census_tract:
type: string
city:
type: string
combined_statistical_area:
type: string
congressional_district:
type: string
elevation_feet:
type: string
fips_code:
type: string
geo_quality:
type: string
house_number:
type: string
land_use_code:
type: string
land_use_group:
type: string
la
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smarty/refs/heads/main/openapi/smarty-us-address-enrichment-api-openapi.yml