Useful Links and Resources
Learn about O Series URIs, endpoints, and additional external resources.
Useful links
| If you are... | Visit... |
|---|---|
| Interested in learning more about this offering | Vertex O Series page |
| An existing client | Vertex Community |
| Using REST APIs with O Series Edge | O Series Edge page |
| Using REST v1 APIs | v1 API documentation |
O Series URIs
Once you get an API key, you can communicate securely from your web application with the API. All API responses are returned in JSON and then converted to language-specific objects.
A Uniform Resource Identifier (URI) is the portion of the URL that does not include the endpoint. It specifies where the service is hosted. The URI that is used to communicate with O Series depends on the platform you are using and the type of call you are making:
| O Series Cloud | URLs |
|---|---|
| Authorization - VERX IDP | https://auth.vertexcloud.com/oauth/token |
| Authorization - Legacy IDP | https://auth.vertexsmb.com/identity/connect/token |
| Token Caching | https://tokenguard.vertexcloud.com/cached/oauth/token |
| Transaction Calls on AWS | https://calcconnect.vertexsmb.com/vertex-ws/<endpoint> |
| Transaction Calls on Azure | https://calcconnect.azure-na.vertexcloud.com/vertex-ws/<endpoint> |
| Transaction Calls on AWS with S/4 HANA | https://s4hanaconnect.vertexsmb.com/vertex-ws/<endpoint> |
| Transaction Calls on Azure with S/4 HANA | https://s4hanaconnect.azure-na.vertexcloud.com/vertex-ws/<endpoint> |
| Configuration | https://calcconnect.vertexsmb.com/tax-config-api/config/<endpoint> |
| O Series On-Demand | URL |
|---|---|
| Authorization | https://<customer>.ondemand.vertexinc.com/oseries-auth/oauth/token |
| Transaction Calls | https://<customer>.ondemand.vertexinc.com/vertex-ws/<endpoint> |
| Configuration | https://<customer>.ondemand.vertexinc.com/tax-config-api/config/<endpoint> |
| User and Role Management | https://<customer>.ondemand.vertexinc.com/oseries-auth/<endpoint> |
| O Series On-Premise | URIs |
|---|---|
| Authorization | https://<servername:port>/oseries-auth/oauth/token/ |
| Transaction Calls | https://<servername:port>/vertex-ws/v2/<endpoint> |
| Configuration | https://<servername:port>/tax-config-api/config/v2/<endpoint> |
| User and Role Management | https://<servername:port>/oseries-auth/<endpoint> |
O Series endpoints
The API endpoint for an O Series API varies depending on the type of request you want to submit:
- Tax Calculation API endpoints: supplies, procurement, and owner.
- Transaction Management API endpoints: transactions by ID, reversal, and transaction exists.
- Tax Area Lookup API endpoints: address, coordinates, tax area ID, external jurisdiction, find tax area, tax area changes, and tax area changes by ID.
- Tax Configuration API endpoints: category, commodity code, driver, location, mapping, registration, and taxpayer.
- Task Management API endpoints: definitions, configurations, tasks, and schedules.
- User Management and Role Management API endpoints: users and roles.
Tax Calculation API endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /supplies | POST - Represents tax calculation from the seller's perspective. Performs a calculation request based on the set property of the Sale Message Type. Valid values are Quotation, Invoice, or Distribute Tax. |
/v2 | /procurement | POST - Represents tax calculation from the buyer's perspective. Performs a calculation request based on the set property of the Purchase Message Type. Valid values are PurchaseOrder, InvoiceVerification, Accrual, DistributeTax, or Evaluated Receipts Settlement (ERS). |
/v2 | /owner | POST - Represents tax calculation from the owner's perspective. Performs a calculation request based on the set property of the Owner Message Type. Valid values are Inventory Removal and Asset Movement |
Transaction Management API endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /transactions/{id} | DELETE - Deletes a transaction stored in the host system. |
/v2 | /transactions/{id}/reversal | POST - Creates a second transaction with negated taxability amounts to "reverse" the original transaction. |
/v2 | /transactions/{id}/rollback | POST - Reverts a transaction to its previous state after having been modified by an ARBillingSync , APInvoiceSync, or AccrualSync synchronization event. |
/v2 | transaction-exists/{transaction id} | GET - Checks if the transaction with the specified transactionId exists. |
Tax Area Lookup API endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /address-lookup | POST - Retrieves tax area information using a postal address as the criteria. The address lookup process takes an address and attempts to verify and cleanse the address by determining possible Vertex-defined tax areas and associated jurisdictions. |
/v2 | /coordinates-lookup | POST - Retrieves tax area information using the latitude and the longitude as the criteria. The coordinates lookup process takes a latitude and a longitude and attempts to determine possible Vertex-defined tax areas and associated jurisdictions. ⚠️This lookup request is not currently available for O Series Cloud deployments. |
/v2 | /taxareaid-lookup | POST - Retrieves tax area information by using the unique Tax Area ID. |
/v2 | /external-jurisdiction-lookup | POST - Retrieves tax area information by using a jurisdiction-defined code. |
/v2 | /find-taxareas | POST - Retrieves tax area information for multiple searches, using any of the available search criteria. |
/v2 | /changed-taxareas | GET - Identifies tax areas that have changed for any reason within a date range. ⚠️This lookup request is not available for O Series tax calculation deployments hosted on Microsoft Azure. |
/v2 | /changed-taxareas/{taxareaid} | GET - Identifies whether a specific tax area has changed for any reason within a date range. ⚠️This lookup request is not available for O Series tax calculation deployments hosted on Microsoft Azure. |
Tax Configuration API endpoints
Category configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-categories | GET - Returns a list of taxability categories ordered by name. You can filter by code and name using the eq operator. |
/v2 | /taxability-categories/{id} | GET - Retrieves a category by id. |
/v2 | /taxability-categories/{id}/hierarchy | GET - Returns a list of the requested taxability category and all its descendants, using pre-order tree traversal. |
Commodity code configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | commodity-codes | GET - Returns a list of supported commodity code types.. |
/v2 | /commodity-codes/{type} | GET - Retrieves a category by id. |
/v2 | /commodity-codes/{type}/{codevalue} | GET - Returns commodity code mapping information for a commodity code. |
Driver configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-drivers | POST - Create a taxability driver. |
/v2 | /taxability-drivers | GET - Returns a list of taxability drivers ordered by code. You can filter by code, name and owningTaxpayerId using the eq operator. |
/v2 | /taxability-drivers/{id} | GET - Retrieve a taxability driver by id. PUT - Update a taxability driver. DELETE - Delete a taxability driver. |
Location configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /locations | POST - Create a taxability driver. GET - Returns a list of taxability drivers ordered by code. You can filter by code, name and owningTaxpayerId using the eq operator. |
/v2 | /locations/{id} | GET - Retrieve a taxability driver by id. PUT - Update a taxability driver. DELETE - Delete a taxability driver. |
Mapping configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-mappings | POST - Create a taxability mapping. GET - Returns a list of taxability mappings ordered by taxability category id. You can filter by categoryId and driverId using the eq operator. |
/v2 | /taxability-mappings/{id} | GET - Retrieve a mapping by id. DELETE - Delete a mapping by id. |
Registration configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /registrations | POST - Create one or more registrations. GET - Returns a list of registrations ordered by owningPartyId. You can filter by owningPartyId and registrationType using the eq operator. |
/v2 | /registrations/{id} | GET - Retrieve a registration by id. PUT - Update a registration configuration by id. All elements are replaced. DELETE - Delete a registration by id. |
Taxpayer configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxpayers | POST - Create a taxpayer. GET - Returns a list of taxpayers ordered by name. You can filter by code and name using the eq operator. |
/v2 | /taxpayers/{id} | GET - Retrieve a taxpayer by id. PUT - Update a taxpayer by id. |
User Management API endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /users | GET - Search for users. POST - Create a user. |
/v2 | /users/{uuid} | GET - Search for a specific user. PUT - Update a user. |
Role Management API endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /roles | GET - List all user roles. |
Updated 4 months ago