Welcome

The Cost to use this API

Use of the TonicDM API has no cost, but it does have rate limits. Understanding the rate limits and using them creatively will enable you to achieve your goals without stressing the TonicDM platform.

Rate Limiting

By limiting the number of API requests that can be issued from a unique authentication token, we are able to offer a more reliable service by protecting our own system infrastructure.

Each endpoint has a parameter: data_quantity=id_only|basic|complete.

• id_only: When pulling lists or searching for records that meet your criteria, this will return just the IDs and last updated timestamp of the records you need. Use your client-side cache for the details of records that are not outdated, and make basic requests for the items you don't have in cache. id_only incurs a rate limiting factor of 1.
• basic: When pulling records, returns only the fields in that record. Details for records included by association are given as IDs and last updated timestamp (for example, the from person in an email record would be just an ID and when that person record was last changed). Use your client-side cache for the details of records that are not outdated, and make a basic request for the referenced items you don't have in cache. basic incurs a rate limiting factor of 5.
• complete: When pulling records, returns all the fields of the item, and all the fields of the items included by reference (for example, the from person would include all the person fields). complete incurs a rate limiting factor of 20.

Use Cases:

• Applications with client-side caching, e.g. data warehousing or Single Page Apps. If your application involves persistance of all data on the client side (such as in a data warehouse), calls to the API can be made with data_quantity=basic which allows you to pull new or updated records with only the IDs and last updated timestamp of linked records. The full data of those linked records may already be in the data warehouse, or if not, they can be retrieved via a separate call for the linked record also made with data_quantity=basic. Updating records should be run as a separate process, either 1) once per day for each object type using the filter updated_after=<prior date> or 2) using WebHooks which will send updated records to your application proactively.
• No client-side caching with data_quantity=complete primarily intended for interactive uses. If your application has no persistance of data on the client side (such as integrations that retrieve data only on an as-needed basis), calls to the API can be made with data_quantity=complete which results in all feilds for the current record and all its linked records being returned.

Managing Rate Limits

The API rate limit scheme is designed to encourage client-side caching for high volume API users.

The TonicDM API rate limit is 3,600 request units per hour. The rate limit resets every hour.

There are three rate limit headers returned when making a request.

• X-Rate-Limit-Limit: The total number of request units you are allowed per 60 minute window.
• X-Rate-Limit-Remaining: The number of request units remaining in the current 60 minute window.
• X-Rate-Limit-Reset: The Unix timestamp for when the next window begins.

For example:

X-Rate-Limit-Limit: 3600
X-Rate-Limit-Remaining: 3599
X-Rate-Limit-Reset: 1466182244

Exceeding the rate limit

When you exceed the rate limit, the client will receive a 429 status code. The rate limit headers will still be present. The response body will contain the following message.

You have surpassed the max number of requests for an hour. Please wait until your limit resets.

In the event your application exceeds the rate limit, wait until your limit resets before making any additional calls. Get the Unix timestamp value of the X-Rate-Limit-Reset header from the response and have your application wait until that time before making any further requests. Event-driven integrations utilizing webhooks should implement a method for queuing jobs so that webhooks can be stored and processed later after your application’s rate limit has refreshed.

If you continue making requests when your rate limit is exceeded, the time until reset will be extended. You will see this in the rate limit headers of the 429 response.

To stay below the rate limit:

• implement client-side caching and data_quantity=id_only if possible.
• use filters to pull pages of responses instead of getting only a single record per call.

Conventions

Naming Conventions

• all lower case with _ as separator,
  eg. /workflow with data_quantity=id_only. Note that paths and parameters are always case-sensitive.
• model/schema uses singular "table" names
• GET=read, PATCH=update, POST=create and DELETE=truly delete (soft delete is a PATCH with status=4).
• Nouns should be in the plural form (/files instead of /file) unless they describe a singleton.
• IDs are UUID without hyphens (32 characters), pattern: '^[0-9a-fA-F]{32}$'

Status codes and how they should be used:

• 200: Successfully read the resource you requested. One or more records are returned in the form of an array.. This response will be returned if a request correctly results in no data (for example a search with zero results).
• 201: Successfully created the resource you sent.
• 204: No content. The request was successfully executed on the server but there is no data to return.
• 400: Bad request. This is a client-side error, for example invalid JSON, missing required fields, wrong parameter types, or invalid data format.
• 401: Authentication is missing or incorrect. This is a client-side error that can be fixed by correctly authenticating.
• 403: Forbidden. The server understands request, the client is identified and authenticated, but access to the resource is denied.
• 404: The resource cannot be found. This is a client-side error. The URL path does not resolve to an API endpoint.
• 429: Surpassed the max number of request units for the current hour.
• 500: The request was valid but there was an error on the server-side.

Non-standard Patterns

Parameter names are prefixed with their function, so instead of the typical id parameter to request a single record, the TonicDM API uses filterIDs indicating that this is a filter to return just the listed IDs and that more than one can be supplied. This system is designed to facilitate client side caching where a list of specific records is needed.

Typical URLs put object IDs in the path and options in the QueryString (eg. /projects/f71f272f752c4307b36c5124688562c4/rfis?status=open&sortby=number). This style is useful for URLs displayed in the browser where they can be bookmarked or shared, but strange for APIs which are intended for programatic interaction. The TonicDM API uses

• URLs to identify endpoints,
• Header Parameters for all options

e.g. v1.0/rfi with the Request Paramaters projectId=f71f272f752c4307b36c5124688562c4, filterStatus=open, sortBy=number).

Definitions

This documentation uses the following terms in the specific ways described below. Terms with special meaning have inital caps in the text. It is important to read through the terms below as they explain how data is structured.

Tenant

A Tenant corresponds to an authentication source. Each TonicDM customer typically has one Tenant in TonicDM.

Many Tenants will have only one domain which serves as both the authentication/UPN and the domain of their email addresses, however the concept of Tenants allows customers to use one authentication source (idp) and have staff with different email domains due to historical brand changes, acquisitions, legal requirements, etc. See Brands below.

Companies or people that use a "shared domain" email address (eg. our-company@gmail.com) will be a tenant-of-one in TonicDM where the Tenant can have only one User (ie. that email address).

As a user of the TonicDM API, you have access only to the data inside your Tenant. Actions in one Tenant can not read or manipulate the data in another Tenant. There is no need to specify your Tenant when make calls to the API since this is determined by your authentication to the API.

The properties of your Tenant can be accessed with the /core/organizations/me endpoint. The data returned is in the same structure as any other Organization record in your Tenant (ie. your Contact Organizations), just with the Tenant Settings fields appended.

Division1 and Division2

Division1 and Division2 are logical groupings within a Tenant. They can be given user-facing names relevant to the Tenant, for example "Market Sector" or "Studio".

Each Staff Member and each Project can be assigned one Division1 and one Division2 (eg. if Division1 is given the name "Market Sector" then a Project or Person must be in either the "Airports" or the "Sports" Market Sector, but can not be in both).

User

A User corresponds to an authenticated person in the Tenant. There is no endpoint to create a User: they are automatically created when someone logs into TonicDM.

The properties of your own User can be accessed with via /core/persons/me. The data returned is in the same structure as any other Person record in your Tenant (ie. your Contact Persons), just with the User Settings fields appended.

Organizations

Organizations are a container for Persons, Offices, and Brands. Your Tenant is just an Organization with the Tenant Settings fields appended. The other Organizations are for your Contacts. From a data structure point of view, the Tenant Organization the Contact Organizations are the same.

Typically the Tenant Organization will be fully built out with all the customers Offices, Brands and Persons, and typically Contact Organizations have very minimal data: usually just one Brand name with one domain and a few relevant people.

• If you don't have the AdvancedContacts license, only your Organization can have Offices and Brands. Your Contact Organizations will be automatically structured such that each domain is a solo Organization/Brand with just the Contacts whose email addresses match that domain.
• If you have the TonicDM AdvancedContacts license, you can input the Offices and Brands of your Contact Organizations. The Brands can be configured for multiple domains, meaning one Organization can be a container for Persons with different email address domains.

Brands

An Organization can have one or more Brands. Brands serve several purposes:

• Compliance: where a different company name and logo are required for some projects due to local registration requirements.
• From acquistion: where the acquired company will keep its original branding.
• Divisional: where a studio within the company uses a different externally facing brand.

Each Organization must have one Brand with at least one Domain. Additional Brands in an Organization can have zero or more Domains. The same Domain can not be associated with more than one Brand.

• If you don't have the AdvancedContacts license, you will not have access to the OrganizationID field in the Brand records outside your own Organization. This means you will not be able to use the OrganizationID field to group data together under a single Organization when that Organization uses multiple Brands. Your Contact Organizations will be automatically structured such that each domain is a solo Organization/Brand.
• If you have the TonicDM AdvancedContacts license, you can input the Brands of your Contact Organizations. The Brands can be configured for multiple domains, meaning one Organization can be a container for multiple Brands with different email address domains.

Offices

An Organization (whether the Tenant Organization or Contact Organization) can have zero or more Offices (physical locations).

Each Person can be optionally be assigned one of the Offices defined in their Organization. Each Project can be optionally be assigned one of the Offices defined in your Organization (Tenant).

• If you don't have the AdvancedContacts license, you will not have access to the OrganizationID field in the Office records outside your own Organization. This means you will not be able to assign Offices (physical locations) to Contacts.
• If you have the TonicDM AdvancedContacts license, you can input the Offices of your Contact Organizations and then assign Offices (physical locations) to the Contacts who are part of that Contact Organization.

Email Addresses, Persons and Staff

Email Address records allow for a contact information like Name, Title etc. and a single email address. Email addresses are automatically assigned one of the following Types: business, personal, system or misspelled, and one of the following delivery statuses: unknown, delivered or bounced.

PersonID links one or more email addresses together for the purposes of representing a physical person who has more than one email address. The email addresses do not have to be at the same domain or even within the same Organization.

• If you don't have the AdvancedContacts license, you will not have access to the PersonID field for EmailAddress records outside your own Organization. This means, except for Staff, you will not be able to use the PersonID field to group data together under a single Person when that person uses multiple email addresses.
• If you have the TonicDM AdvancedContacts license, you will be able to use the PersonID field to group data together by Person even when people use multiple email addresses. One of the Email Address records can be set as isPrime, meaning that data will be used when showing the info at the Person level, and email addresses can have a start and end date, allowing you to maintain consistent records as a person moves between companies.

When a user has more than one Email Address, the Email Address with the Brand's assigned Domain will be preferenced in the context of those Projects associated with that Brand.

Staff are Persons in your Organization with an email address of Type business. Remember that even without the AdvancedContacts license, you will still have access to the Offices, Brands and Persons features for your own Organization. If a firm has 2 employees: One and Two, with email addresses one@pacific-architects.com and two@pacific-architects.com, and Two also has an email address for two@pacific-engineers.com, and there are general purpose email addresses for info@pacific-architects.com and info@pacific-engineers.com, then the Staff List will show 2 items. The staff list can be accessed via /core/organizations/me/staff.

Data Residency

As a TonicDM customer, your organization's general data (eg. the list of projects, the organization's contacts, etc.) are stored in your organization's home zone. API calls can be made through any of the API servers. If the project information, your organization information, and the API server are all in the same zone, then the data will have been fully resident in that zone.

• To find your Organization's home zone, use: /core/me.
• To find the Zone where your Project's data is stored, use /core/projects.