Extractor Management API (v3)

All custom integration / ETL ought to behave/operate in the exact same way. Adhering to this documentation will allow this


  • extractor_to_avalara_token: Formerly known as connector_2_tf_token, identifies the extractor and restricts access to environments / version of TF API the extractor is certified for (see below for token usage in header)
  • avalara_to_extractor_token: Formerly known as the trustfile_2_connector_token, authorizes Trustfile (and other consumers), and Extractor to access operate the extractor micro-service API
  • connectionId: identifies and authorizes access to the Trustfile (or CUP) company to push data into. Mapped to a UUID Company Token in database


  • Extractor will be the source of truth for all extractor tokens etc
  • Disabling/updating an extractor will go through Extractor

Extractor Management API responsibility

  • Integrating with Extractor Items API
  • Integrating with host system API, including authorization (typically something like oAuth)
  • ETL of sales/refunds/tax/shipping data into TrustFile data model
  • Basic management of user data sources: CRUD, enable/disable/status
  • Scheduling and load balancing of users data synchronization
  • Data integrity. It is the responsibility of the extractor micro-service to know what data has been processed by Extractor.

Extractor Management API is not responsible for

  • User experience
  • Branding of experience (aside from the popup for authentication with host system)

Provisioning of TFO by extractors - workflow

  • Create a user in the extractor db, enabled should be false, startDate should be null (extractor should not be syncing)
  • Call TFO signup: /v4/company/signup
  • In TFO, a modal will pop up which will allow the user to set the startDate, which will call PUT /connections/{connectionId} with the following example body: { "enabled": true, "startDate": "2018-04-01" }

Hosting / Language

  • All extractors will be hosted and operated from the Heroku PaaS
  • Language: choose between - Ruby/Node/Java
  • DB: Postgres (on heroku)

Dates and Timestamps

  • Dates are in yyyy-mm-dd format
  • Timestamps are in the ISO format: 2015-07-06T22:26:28+00:00
  • Timestamps are in UTC +00:00 timezone


Put localization configs (specific to a given environment) into environment variables. Document the required variables in the README.md of the project. https://devcenter.heroku.com/articles/config-vars


API requests except orangez/health are authorized with Header param

Authorization: Bearer avalara_to_extractor_token