{"openapi":"3.0.0","info":{"title":"Vertex Tax Configuration API","description":"Vertex REST API end points for Tax Configuration services. Copyright © 2022 Vertex, Inc. All rights reserved.","version":"v2.1.0"},"servers":[{"url":"/tax-config-api","description":"Vertex Tax Configuration API"}],"tags":[{"name":"Pagination","description":"

On API endpoints that support the query options $skip and $top, pagination may be performed with a combination of both.

"},{"name":"Filtering","description":"

Filtering may be performed on the majority of \"GET\" endpoints. The full list of supporting filtering operations follows, but check each endpoint for the specific list of operators and properties that may be used. We use OData Filter

OperatorDescription
eqEquals. Checks if the values of two operands are equal. If they are, the condition is true.
neNot equal. Checks if the values of two operands are not equal. If they are not, the condition is true.
gtGreater than. Checks if the value of the first operand is greater than that of the second. If it is, the condition is true.
geGreater than or equal to. Checks if the value of the first operand is greater than or equal to that of the second. If it is, the condition is true.
ltLess than. Checks if the value of the first operand is less than that of the second. If it is, the condition is true.
leLess than or equal to. Checks if the value of the first operand is less than or equal to that of the second. If it is, the condition is true.
\n
String FunctionDescription
containsReturns a record if a field contains a specified value. For example, contains(name,'beverage').
"},{"name":"category","description":"Taxability Category configuration domain"},{"name":"commoditycode","description":"Commodity Code configuration domain"},{"name":"driver","description":"Taxability Driver configuration domain"},{"name":"location","description":"Location configuration domain"},{"name":"mapping","description":"Taxability Mapping configuration domain"},{"name":"registration","description":"Registration configuration domain"},{"name":"taxpayer","description":"Taxpayer configuration domain"}],"paths":{"/config/v2/taxability-categories":{"get":{"tags":["category"],"summary":"Retrieves taxability categories","description":"Returns a list of taxability categories ordered by name. You can filter by code and name using 'eq' operator. For example, code eq 'Med Items by RX', name eq 'Medical Items Sold Under Prescription', code eq 'Med Items by RX' and name eq 'Medical Items Sold Under Prescription'.","operationId":"ListCategories","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityCategorySearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-categories/{id}":{"get":{"tags":["category"],"summary":"Retrieve a category by id","description":"Retrieve a category by id","operationId":"GetCategoryById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"categoryId","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityCategory"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-categories/{id}/hierarchy":{"get":{"tags":["category"],"summary":"Retrieve taxability categories","description":"Returns a list of the requested taxability category, and all its descendants, using pre-order tree traversal.","operationId":"ListCategoryHierarchy","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"taxability category id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityCategorySearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/commodity-codes":{"get":{"tags":["commoditycode"],"summary":"Returns a list of supported commodity code types.","description":"Returns a list of supported commodity code types.","operationId":"ListCommodityCodeTypes","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/commodity-codes/{type}":{"get":{"tags":["commoditycode"],"summary":"Returns a list of commodity codes available for a particular type.","description":"Returns a list of commodity codes available for a particular type ordered by code. You can filter by name using 'contains' String Function. For example, contains(name, 'Iced tea'). Case-insensitive search is supported.","operationId":"GetCommodityCodesByType","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"type","in":"path","description":"Commodity code type","required":true,"schema":{"type":"string","minLength":1,"maxLength":60}},{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommodityCodeSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/commodity-codes/{type}/{codevalue}":{"get":{"tags":["commoditycode"],"summary":"Returns commodity code mapping information for a commodity code.","description":"Returns commodity code mapping information for a commodity code.","operationId":"GetCommodityCode","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"type","in":"path","description":"Commodity code type","required":true,"schema":{"type":"string","minLength":1,"maxLength":60}},{"name":"codevalue","in":"path","description":"Commodity code value","required":true,"schema":{"type":"string","minLength":1,"maxLength":40}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommodityCode"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-drivers":{"post":{"tags":["driver"],"summary":"Create a taxability driver","description":"Create a taxability driver","operationId":"CreateDriver","security":[{"oauth2":["api.configuration.editconfiguration"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityDriverBase"}}},"description":"Configuration of taxability driver to be created","required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityDriver"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}},"get":{"tags":["driver"],"summary":"Retrieve taxability drivers","description":"Returns a list of taxability drivers ordered by code. You can filter by code, name, owningPartyCode, owningPartyName and owningTaxpayerId using 'eq' operator. For example, code eq 'clothing', name eq 'product class for clothing', owningTaxpayerId eq '37f038e2-22ec-4e5b-93f4-f065bea65542' and code eq 'clothing'.","operationId":"ListDrivers","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityDriverSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-drivers/{id}":{"get":{"tags":["driver"],"summary":"Retrieve a taxability driver by id","description":"Retrieve a taxability driver by id","operationId":"GetDriverById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"driver id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityDriver"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"put":{"tags":["driver"],"summary":"Update a taxability driver","description":"Update a taxability driver","operationId":"UpdateDriver","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"driver id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityDriverBase"}}},"description":"Full replace of driver","required":true},"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"delete":{"tags":["driver"],"summary":"Deletes the driver","description":"Deletes the driver","operationId":"DeleteDriver","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"driver id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/locations":{"post":{"tags":["location"],"summary":"Create one or more locations","description":"Create one or more locations.","operationId":"CreateLocation","security":[{"oauth2":["api.configuration.editconfiguration"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LocationBase"}}}},"description":"Configuration of the location or locations to be created.","required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}},"get":{"tags":["location"],"summary":"Retrieve locations","description":"Returns a list of locations ordered by owningPartyId. You can filter by owningPartyName, owningPartyCode, owningPartyId and expiredIndicator using 'eq' operator. 'expiredIndicator' filter is used to retrieve locations that are no longer active i.e. their end date is prior to today. For example, owningPartyId eq '37f038e2-22ec-4e5b-93f4-f065bea65542', expiredIndicator eq 'true'.","operationId":"ListLocations","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/locations/{id}":{"get":{"tags":["location"],"summary":"Retrieve a location by id","description":"Retrieve a location by id","operationId":"GetLocationById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"location id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"put":{"tags":["location"],"summary":"Update location configuration","description":"Update a location configuration. All elements are replaced.","operationId":"UpdateLocation","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"location id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationBase"}}},"description":"Full replace of location","required":true},"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"delete":{"tags":["location"],"summary":"Deletes the location","description":"Deletes the location","operationId":"DeleteLocation","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"location id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-mappings":{"post":{"tags":["mapping"],"summary":"Create a taxability mapping","description":"Create a taxability mapping","operationId":"CreateMapping","security":[{"oauth2":["api.configuration.editconfiguration"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityMappingBase"}}},"description":"Configuration of taxability mapping to be created","required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityMapping"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}},"get":{"tags":["mapping"],"summary":"Retrieve taxability mappings","description":"Returns a list of taxability mappings ordered by taxability category id. You can filter by owningPartyName, owningPartyCode, categoryName, driverName, categoryId and driverId using 'eq' operator. For example, categoryId eq '37f038e2-22ec-4e5b-93f4-f065bea65542', categoryId eq '37f038e2-22ec-4e5b-93f4-f065bea65542' and driverId eq '3d756706-43a3-4287-b1ac-c28a989d18e2'.","operationId":"ListMappings","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityMappingSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxability-mappings/{id}":{"get":{"tags":["mapping"],"summary":"Retrieves a taxability mapping by id","description":"Retrieves a taxability mapping by id.","operationId":"GetMappingById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"mapping id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxabilityMapping"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"delete":{"tags":["mapping"],"summary":"Deletes the mapping","description":"Delete the mapping","operationId":"DeleteMapping","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"mapping id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/registrations":{"post":{"tags":["registration"],"summary":"Create one or more registrations","description":"Create one or more registrations.","operationId":"CreateRegistration","security":[{"oauth2":["api.configuration.editconfiguration"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RegistrationBase"}}}},"description":"Configuration of the registration or registrations to be created.","required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Registration"}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}},"get":{"tags":["registration"],"summary":"Retrieve registrations","description":"Returns a list of registrations ordered by owningPartyId. You can filter by owningPartyName, owningPartyCode, owningPartyId, expiredIndicator and registrationType using 'eq' operator. 'expiredIndicator' filter is used to retrieve registrations that are no longer active i.e. their end date is prior to today. For example, owningPartyId eq '37f038e2-22ec-4e5b-93f4-f065bea65542', registrationType eq 'IMPORT_ONE_STOP_SHOP', owningPartyId eq '37f038e2-22ec-4e5b-93f4-f065bea65542' and registrationType eq 'IMPORT_ONE_STOP_SHOP', expiredIndicator eq 'true'.","operationId":"ListRegistrations","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/registrations/{id}":{"get":{"tags":["registration"],"summary":"Retrieve a registration by id","description":"Retrieve a registration by id","operationId":"GetRegistrationById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"registration id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"put":{"tags":["registration"],"summary":"Update registration configuration","description":"Update a registration configuration. All elements are replaced.","operationId":"UpdateRegistration","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"registration id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationBase"}}},"description":"Full replace of registration","required":true},"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"delete":{"tags":["registration"],"summary":"Deletes the registration","description":"Deletes the registration","operationId":"DeleteRegistration","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"registration id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxpayers":{"post":{"tags":["taxpayer"],"summary":"Create a taxpayer","description":"Create a taxpayer","operationId":"CreateTaxpayer","security":[{"oauth2":["api.configuration.editconfiguration"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerBase"}}},"description":"Configuration of the taxpayer or taxpayers to be created.","required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Taxpayer"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}},"get":{"tags":["taxpayer"],"summary":"List taxpayers","description":"Returns a list of taxpayers ordered by name. You can filter by code, expiredIndicator and name using 'eq' operator. For example, code eq 'abc', name eq 'Old Navy', code eq 'abc' and name eq 'Old Navy', expiredIndicator eq 'true'.","operationId":"ListTaxpayers","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/Top"},{"$ref":"#/components/parameters/Filter"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerSearchResponse"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"503":{"$ref":"#/components/responses/503"}}}},"/config/v2/taxpayers/{id}":{"get":{"tags":["taxpayer"],"summary":"Get a taxpayer by id","description":"Get a taxpayer by id","operationId":"GetTaxpayerById","security":[{"oauth2":["api.configuration.viewconfiguration","api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"taxpayer id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Taxpayer"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}},"put":{"tags":["taxpayer"],"summary":"Update a taxpayer","description":"Update a taxpayer","operationId":"UpdateTaxpayer","security":[{"oauth2":["api.configuration.editconfiguration"]}],"parameters":[{"name":"id","in":"path","description":"taxpayer id","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerBase"}}},"description":"Full replace of taxpayer","required":true},"responses":{"204":{"description":"successful operation"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"503":{"$ref":"#/components/responses/503"}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"{BaseURL}/authorize","scopes":{"api.configuration.viewconfiguration":"Read or query for one or more entities","api.configuration.editconfiguration":"Create, update or delete an entity"}}}}},"parameters":{"Skip":{"name":"$skip","in":"query","description":"OData pagination number of records to skip. See http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionskip","required":false,"schema":{"type":"integer","minimum":0,"default":0}},"Top":{"name":"$top","in":"query","description":"OData pagination number of items to return. See http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptiontop","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":20}},"Filter":{"name":"$filter","in":"query","description":"The $filter system query option restricts the set of items returned. See http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionfilter","required":false,"schema":{"type":"string"}}},"schemas":{"SearchResponse":{"type":"object","properties":{"count":{"type":"integer","format":"int32","description":"The number of records returned."},"truncated":{"type":"boolean","description":"True if there are more records available beyond the number of records returned in this response. False if there are no more records available for the search criteria requested."}}},"UUID":{"type":"string","description":"Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122)","example":"123e4567-e89b-12d3-a456-426614174000","pattern":"[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}"},"TaxabilityCategoryBase":{"required":["code","name","startDate"],"properties":{"code":{"type":"string","minLength":1,"maxLength":60,"description":"Taxability category code."},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Taxability category name."},"description":{"type":"string","minLength":0,"maxLength":1000,"description":"A long description of the category."},"parentCategoryId":{"$ref":"#/components/schemas/UUID"},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the taxability category becomes effective."},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the taxability category is no longer effective."}}},"TaxabilityCategory":{"description":"Taxability Category","type":"object","required":["id","userDefined"],"allOf":[{"$ref":"#/components/schemas/TaxabilityCategoryBase"},{"properties":{"id":{"$ref":"#/components/schemas/UUID"},"userDefined":{"type":"boolean","default":false,"description":"True if this is a custom, user-defined category."}}}]},"TaxabilityCategorySearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/TaxabilityCategory"},"description":"Collection of taxability categories."}}}]},"VertexError":{"type":"object","required":["errorCode","errorMessage"],"properties":{"errorCode":{"type":"string","pattern":"^[A-Z0-9_]+$","description":"A short Vertex error code that end users can provide while calling our support personnel to report an issue.\nApplications can define their own error codes.\n"},"errorMessage":{"type":"string","description":"A detailed error message describing the error."}}},"CommodityCodeMapping":{"type":"object","description":"The taxability categories this commodity code maps to.","properties":{"taxabilityCategoryId":{"$ref":"#/components/schemas/UUID"},"categoryName":{"type":"string","minLength":1,"maxLength":60,"description":"The taxability category name."},"categoryDescription":{"type":"string","minLength":0,"maxLength":1000,"description":"The taxability category description."},"mappingNote":{"type":"string","minLength":0,"maxLength":1000,"description":"This field indicates when a commodity code is not granular enough to map to a particular Vertex-supplied taxability category. When this is the case, Vertex Tax Research maps to the Vertex taxability category that gives the highest percentage of correct answers."},"startDate":{"type":"string","format":"date","example":"2022-01-01","description":"The date when the commodity code mapping becomes effective."},"endDate":{"type":"string","format":"date","example":"2022-12-31","description":"The date after which the commodity code mapping is no longer effective."}}},"CommodityCode":{"type":"object","properties":{"type":{"type":"string","minLength":1,"maxLength":60,"description":"The commodity code type."},"code":{"type":"string","minLength":1,"maxLength":40,"description":"The commodity code value."},"name":{"type":"string","minLength":1,"maxLength":60,"description":"The commodity code name."},"userDefined":{"type":"boolean","default":false,"description":"True if this is a user-defined commodity code."},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/CommodityCodeMapping"}}}},"CommodityCodeSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"commodityCodes":{"type":"array","items":{"$ref":"#/components/schemas/CommodityCode"},"description":"Collection of Commodity Code entities."}}}]},"DriverTypeEnum":{"type":"string","description":"The taxability driver types.","enum":["PRODUCT","PRODUCT_CLASS","USAGE","USAGE_CLASS","BUYER_CONDITION","SELLER_CONDITION","CNAE_BUYER","CNAE_SELLER","NATURE_OF_FISCAL_OPERATION"]},"FinancialEventPerspectiveEnum":{"type":"string","description":"Financial Event Perspective","enum":["SUPPLIES","PROCUREMENT","BOTH"]},"TaxabilityDriverKey":{"type":"object","properties":{"driverName":{"type":"string","description":"Taxability Driver Name."},"driverCode":{"type":"string","description":"Taxability Driver Code."},"driverId":{"$ref":"#/components/schemas/UUID","description":"Taxability Driver UUID."}}},"MappedEntities":{"type":"object","description":"The entities that can be mapped to a taxability category. You can map a taxpayer to a category, a taxability driver to a category, a taxpayer and a taxability driver to a category, or map different types of drivers to a category.","properties":{"taxpayerId":{"$ref":"#/components/schemas/UUID"},"driverIds":{"type":"array","items":{"$ref":"#/components/schemas/UUID"},"description":"Collections of the taxability drivers"},"owningTaxpayerCode":{"type":"string","description":"External System identifier for the owning taxpayer. This is returned in the response but cannot be specified in the request."},"owningTaxpayerName":{"type":"string","description":"Full Name for the owning taxpayer. This is returned in the response but cannot be specified in the request."},"taxabilityDriverKeyList":{"type":"array","items":{"$ref":"#/components/schemas/TaxabilityDriverKey"},"description":"Collection of Taxability Driver Key Info"}}},"TaxabilityMappingBaseBrazilDriver":{"type":"object","required":["categoryId"],"properties":{"mappedEntities":{"$ref":"#/components/schemas/MappedEntities"},"categoryId":{"$ref":"#/components/schemas/UUID"},"taxabilityCategoryName":{"type":"string","description":"Name for the taxability category. This is returned in the response but cannot be specified in the request."},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the taxability mapping becomes effective"},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the taxability mapping is no longer effective"},"note":{"type":"string","minLength":0,"maxLength":1000,"description":"A free-form text for additional driver information."}}},"TaxabilityDriverBase":{"type":"object","required":["code","name","driverType","startDate"],"properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"External System identifier for the driver."},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Full Name for driver."},"note":{"type":"string","minLength":0,"maxLength":1000,"description":"A free-form text for additional driver information."},"owningTaxpayerId":{"$ref":"#/components/schemas/UUID"},"owningTaxpayerCode":{"type":"string","description":"External System identifier for the owning taxpayer. This is returned in the response but cannot be used in the request."},"owningTaxpayerName":{"type":"string","description":"Full Name for the owning taxpayer. This is returned in the response but cannot be used in the request."},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the taxability driver becomes effective."},"driverType":{"$ref":"#/components/schemas/DriverTypeEnum"},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the taxability driver is no longer effective."},"financialEventPerspective":{"$ref":"#/components/schemas/FinancialEventPerspectiveEnum"},"mapping":{"$ref":"#/components/schemas/TaxabilityMappingBaseBrazilDriver"}}},"TaxabilityMappingBase":{"type":"object","required":["mappedEntities","categoryId","startDate"],"properties":{"mappedEntities":{"$ref":"#/components/schemas/MappedEntities"},"categoryId":{"$ref":"#/components/schemas/UUID"},"taxabilityCategoryName":{"type":"string","description":"Name for the taxability category. This is returned in the response but cannot be specified in the request."},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the taxability mapping becomes effective"},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the taxability mapping is no longer effective"},"note":{"type":"string","minLength":0,"maxLength":1000,"description":"A free-form text for additional driver information."}}},"TaxabilityMapping":{"description":"Taxability Mapping","type":"object","required":["id"],"allOf":[{"$ref":"#/components/schemas/TaxabilityMappingBase"},{"properties":{"id":{"$ref":"#/components/schemas/UUID"}}}]},"TaxabilityDriver":{"description":"Taxability Driver","type":"object","required":["id"],"allOf":[{"$ref":"#/components/schemas/TaxabilityDriverBase"},{"properties":{"id":{"$ref":"#/components/schemas/UUID"},"taxabilityMapping":{"$ref":"#/components/schemas/TaxabilityMapping"}}}]},"TaxabilityDriverSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"drivers":{"type":"array","items":{"$ref":"#/components/schemas/TaxabilityDriver"},"description":"Collection of Taxability Driver entities."}}}]},"PostalAddress":{"type":"object","description":"A postal address for a location.","properties":{"city":{"type":"string","description":"The city name for the postal address.","minLength":0,"maxLength":60},"country":{"type":"string","description":"The country name for the postal address.","minLength":0,"maxLength":60},"mainDivision":{"type":"string","description":"The main division (e.g. State) name for the postal address.","minLength":0,"maxLength":60},"postalCode":{"type":"string","description":"The postal code for the postal address.","minLength":0,"maxLength":20},"streetAddress1":{"type":"string","description":"The first street line for the postal address.","minLength":0,"maxLength":100},"streetAddress2":{"type":"string","description":"The second street line for the postal address.","minLength":0,"maxLength":100},"subDivision":{"type":"string","description":"The subdivision (e.g. County) name for the postal address.","minLength":0,"maxLength":60}}},"LocationBase":{"type":"object","required":["taxAreaId","owningPartyId","locationCode","name","registrationCode","startDate","postalAddress"],"properties":{"taxAreaId":{"type":"string","description":"The distinct tax area identifier for the location."},"locationCode":{"type":"string","description":"A client specified code for the location.","minLength":1,"maxLength":20},"name":{"type":"string","description":"A client specified name for the location.","minLength":1,"maxLength":60},"owningPartyId":{"$ref":"#/components/schemas/UUID"},"owningPartyCode":{"type":"string","description":"External System identifier for the owning party. This is returned in the response but cannot be used in the request."},"owningPartyName":{"type":"string","description":"Full Name for the owning party. This is returned in the response but cannot be used in the request."},"postalAddress":{"$ref":"#/components/schemas/PostalAddress"},"registrationCode":{"type":"string","description":"A tax authority specified identifier for the location.","minLength":1,"maxLength":20},"startDate":{"type":"string","format":"date","example":"2022-01-01","description":"The date when the location becomes effective."},"endDate":{"type":"string","format":"date","example":"2022-12-01","description":"The date after which the location is no longer effective."}}},"Location":{"description":"Location configuration","allOf":[{"$ref":"#/components/schemas/LocationBase"},{"type":"object","required":["id"],"properties":{"id":{"$ref":"#/components/schemas/UUID"}}}]},"LocationSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/Location"},"description":"Collection of Location entities."}}}]},"TaxabilityMappingSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"mappings":{"type":"array","items":{"$ref":"#/components/schemas/TaxabilityMapping"},"description":"Collection of Taxability Mapping entities."}}}]},"JurisdictionTypeEnum":{"type":"string","example":"STATE","description":"Identifies the common classification of a jurisdiction, based on its geopolitical or taxing context. Note only COUNTRY, STATE, PROVINCE, and TERRITORY are valid for POST & PUT operations.","enum":["APO","BOROUGH","CITY","COUNTRY","COUNTY","DISTRICT","FPO","LOCAL_IMPROVEMENT_DISTRICT","PARISH","PROVINCE","SPECIAL_PURPOSE_DISTRICT","STATE","TERRITORY","TOWNSHIP","TRADE_BLOCK","TRANSIT_DISTRICT"]},"JurisdictionLevelEnum":{"type":"string","example":"MAIN_DIVISION","description":"The level of the jurisdiction for which the tax on the line item is applied. Note only COUNTRY and MAIN_DIVISION are supported for POST & PUT operations.","enum":["COUNTRY","MAIN_DIVISION","SUB_DIVISION","CITY","DISTRICT"]},"RegisteredJurisdiction":{"type":"object","description":"Represents a government entity. The jurisdiction is best identified by the globally unique id property. Otherwise, jurisdictions provided on request will be matched based on the other properties that are available to the requester, such as name, country, and level. These must be sufficient to uniquely identify the jurisdiction.","properties":{"parentCountry":{"type":"string","description":"The country in which this jurisdiction resides."},"parentMainDivision":{"type":"string","description":"The main division of this jurisdiction, which is a State, Territory, or a similar main division of a country."},"name":{"type":"string","description":"Jurisdiction Name or other identifier, such as a two letter State abbreviation."},"vertexJurisdictionId":{"type":"integer","format":"int64","description":"The Vertex-specific number that identifies a jurisdiction."},"type":{"$ref":"#/components/schemas/JurisdictionTypeEnum"},"level":{"$ref":"#/components/schemas/JurisdictionLevelEnum"},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the jurisdiction becomes effective."},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the jurisdiction is no longer effective."}}},"PartyTypeEnum":{"type":"string","enum":["TAXPAYER","CUSTOMER","VENDOR","REGULATED_TAXPAYER","UNREGULATED_TAXPAYER"],"description":"The party types."},"RegistrationTypeEnum":{"type":"string","description":"Registration Type indicates the category to which this registration belongs.","enum":["VAT_REGISTRATION","FEDERAL_EMPLOYER_IDENTIFICATION_NUMBER","TAX_IDENTIFICATION_NUMBER","SOCIAL_SECURITY_NUMBER","BUSINESS_NUMBER","STATE_IDENTIFICATION_NUMBER","NON_UNION_SCHEME","UNION_SCHEME","IMPORT_ONE_STOP_SHOP"]},"RegistrationBase":{"type":"object","required":["owningPartyId","registeredJurisdiction","startDate"],"properties":{"registeredJurisdiction":{"$ref":"#/components/schemas/RegisteredJurisdiction"},"owningPartyId":{"$ref":"#/components/schemas/UUID"},"owningPartyCode":{"type":"string","description":"External System identifier for the owning party. This is returned in the response but cannot be used in the request."},"owningPartyName":{"type":"string","description":"Full Name for the owning party. This is returned in the response but cannot be used in the request."},"owningPartyType":{"$ref":"#/components/schemas/PartyTypeEnum"},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the registration becomes effective."},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the registration is no longer effective."},"registrationType":{"$ref":"#/components/schemas/RegistrationTypeEnum"},"registrationNumber":{"type":"string","minLength":0,"maxLength":40,"description":"A tax jurisdiction assigned number. Registration number is required for registration types UNION_SCHEME, NON_UNION_SCHEME, and IMPORT_ONE_STOP_SHOP."},"physicalPresence":{"type":"boolean","default":false,"description":"True if the business entity has a physical location in the jurisdiction."},"filingCurrencyIsoCode":{"type":"string","minLength":3,"maxLength":3,"description":"The ISO 4217 Alpha-3 code for the currency used for tax filing in the country of registration. This value is required for registration types UNION_SCHEME, NON_UNION_SCHEME, and IMPORT_ONE_STOP_SHOP."}}},"Registration":{"type":"object","required":["id"],"allOf":[{"$ref":"#/components/schemas/RegistrationBase"},{"properties":{"id":{"$ref":"#/components/schemas/UUID"}}}]},"RegistrationSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"registrations":{"type":"array","items":{"$ref":"#/components/schemas/Registration"},"description":"Collection of Registration entities."}}}]},"ShippingTermsEnum":{"type":"string","description":"Shipping Terms determine the point in a transaction at which title transfer of goods takes place, which impacts identification of the taxing jurisdiction.","enum":["EXW","FCA","FAS","FOB","CFR","CIF","CPT","CIP","DAF","DES","DEQ","DDU","DDP","DAP","DAT","SUP","CUS","DPU"]},"DiscountCategoryEnum":{"type":"string","description":"Discount Category is used to select the default type of discount that is applied to all transactions for a given taxpayer. The discount categories are automatically mapped to taxability categories of the same name. These taxability categories specify the Vertex-defined basis rule and calculation rule to use for that discount category for a particular jurisdiction.","enum":["GENERAL_DISCOUNT","CASH_DISCOUNT","MANUFACTURERS_COUPON","RETAILERS_COUPON","TRADE_DISCOUNT","QUANTITY_DISCOUNT","EARLY_PAYMENT_DISCOUNT","FLEXIBLE_DISCOUNT"]},"DiscountMapping":{"type":"object","properties":{"discountCategory":{"$ref":"#/components/schemas/DiscountCategoryEnum"},"discountCode":{"type":"string","minLength":1,"maxLength":20,"description":"The discount code."}}},"TaxpayerBase":{"type":"object","required":["code","name","startDate"],"properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"External System identifier for the taxpayer."},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Full Name for the taxpayer."},"partyTypeId":{"type":"integer","description":"Type of taxpayer (1=Normal, 4=Regulated, 5=Unregulated)"},"note":{"type":"string","minLength":0,"maxLength":1000,"description":"A free-form text for additional taxpayer information."},"parentTaxpayerId":{"$ref":"#/components/schemas/UUID"},"startDate":{"type":"string","format":"date","example":"2021-01-01","description":"The date when the taxpayer becomes effective."},"endDate":{"type":"string","format":"date","example":"2021-12-01","description":"The date after which the taxpayer is no longer effective."},"adoptParentSetup":{"type":"boolean","default":false,"description":"Adopt Parent Setup indicates that the current taxpayer entity inherits the tax exceptions of its parent taxpayer."},"filingEntity":{"type":"boolean","default":true,"description":"Indicates that the taxpayer is responsible for collecting and remitting taxes by filing tax returns."},"shippingTerms":{"$ref":"#/components/schemas/ShippingTermsEnum"},"discountMappings":{"type":"array","items":{"$ref":"#/components/schemas/DiscountMapping"},"description":"Collection of discount mappings"}}},"Taxpayer":{"description":"Taxpayer configuration","type":"object","required":["id"],"allOf":[{"$ref":"#/components/schemas/TaxpayerBase"},{"properties":{"id":{"$ref":"#/components/schemas/UUID"}}}]},"TaxpayerSearchResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/SearchResponse"},{"properties":{"taxpayers":{"type":"array","items":{"$ref":"#/components/schemas/Taxpayer"},"description":"Collection of Taxpayer entities."}}}]}},"responses":{"400":{"description":"Bad Request. The request was invalid (did not have a required parameter) or 1 or more parameters on the request was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VertexError"}}}},"401":{"description":"Authentication failure. There was no credential attached to the request, or the credential was invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VertexError"}}}},"403":{"description":"Authorization failure. The user or identity requesting the operation did not have the requisite role to perform the operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VertexError"}}}},"404":{"description":"The entity you were querying or updating does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VertexError"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VertexError"}}}}}},"x-readme":{"explorer-enabled":false,"proxy-enabled":true}}