Atlas API: Getting started

Welcome to the ATLAS Developer Portal. This guide will help with setting up a connection to the ATLAS APIs, as well as explaining the main concepts of how the APIs are structured and used.

ATLAS Developer Account

To start making requests to the ATLAS platform and build your integration, you first need an ATLAS Developer Account. Contact your Sales associate and ask to be referred to the API Support team and we will supply you with a Developer Account that is suitable for building and testing your integrations.

Developer Portal

API documentation is a living thing. Our APIs are continuously being developed and so the API documentation is often updated. We use tools to dynamically create our technical API documentation and you will find all API documentation in this Developer Portal under APIs.

To login to this Developer Portal you use your ATLAS Developer Account.

Our APIs will constantly update, but we do aim to do this in a backwards compatible manner. This means that your client code should allow for unknown properties in the JSON responses, as we can always add more properties to existing endpoint responses. Similarly, we may change or add parameters, headers or properties in our API endpoints. We will log upcoming changes and updates under News and major changes via email.

Products

Products are APIs or groups of APIs. To use the APIs in a product you need to login to the Developer Portal and subscribe to that product. This way you will obtain a Subscription Key for that product. You will need this key to be able to make requests to the APIs in the product. See subsection 'Subscription Keys' below.

Authorization & Authentication

The ATLAS APIs utilize a few layers of security. We'll explain the basic concepts in this section.

ATLAS Login

Almost all requests to the ATLAS APIs require to be made in name of an ATLAS user. This is done through a bearer token (see subsection 'Bearer Token' below).

An ATLAS Developer Account will be created for you by our API Support team. You can use this account to login to the ATLAS portal, the frontend of ATLAS.

Your ATLAS account can be used to log into the ATLAS portal which can be of great help to see whether your API calls had the intended effect. In the portal you can review your imports, items, buckets, orders, and more (see next subsections).

Use the Users API to execute a login against the ATLAS platform and obtain an Authorization JWT token.

Bearer Token

User authorization in ATLAS is done through a so-called bearer token or JSON Web Token (JWT).
This token needs to be included in (almost) every API call you make as a http header with name Authorization

Authorization: bearer <token goes here>

The bearer token is only valid for a short amount of time, and can be retrieved for your user account in two ways:

  • Programmatically through the login endpoint, your token is returned after executing a login.

  • Manually through the ATLAS Portal. Inspect the network calls and copy your token from one of the many calls the frontend makes to the Atlas backend.

The token is a JWT token and can therefore be decoded with websites like jwt.io . This can be helpful to see your account information.

Subscription Key

Subscription keys are unique 32-character strings. These keys are an extra layer of authorisation used in the ATLAS APIs. They are gained by logging into this Developer Portal and subscribing to a product (e.g. Companies Service). This will render a subscription key that must be passed on as header with name Ocp-Apim-Subscription-Key whenever making requests to endpoints in that product.

Ocp-Apim-Subscription-Key:  <key goes here>

Currently, the ATLAS APIs do not enforce the use of a subscription key. This will change in the future, and we will update you when that happens. We recommend you build your integrations with the subscription keys already passed along in the headers.

Company and Buyer Scoping

In the documentation of some endpoints you will find an optional or required query parameter called companyScopeIds and/or buyerScopeIds. These query parameters are used to scope the request down to a specific sub-view of our data.

For most API integrations the companyScopeIds will need your companyId as a value. This id can be found by decoding your jwt token as described in the Bearer token subsection or by retrieving your company information through the Companies API.

Although the companyScopeIds parameter may be shown as optional, it can still be required for non-admin accounts. We are working on making these optional for every user by automatically filling in the value. This is not yet the case on some endpoints.

API Areas

ATLAS is split up in three different logical areas, which we'll explain in this section.

Pre-auction

The pre-auction area is all about the set-up for the auction. Here we create items, attach images to those items, add items to buckets, and set-up auctions to publish to the auctioning platforms like BVA and Troostwijk.

Auction

Auctions are mostly run on "external platforms" like BVA and Troostwijk. The ATLAS APIs don't directly tie into live auction data.

Post-auction

After an auction is closed, the items are sold and invoiced through ATLAS. The order data can then be shared through the APIs.

Entities

In this section will briefly look at some main domain entities you can come across while using the Atlas APIs.

Companies/Sellers

Each seller has its own company on Atlas. All items and contracts will be linked to that company.
Each user in a company can see the imports and items that belong to that company. A user can belong to multiple companies. A non-admin user can only create imports and items under his/her own company.

Company-Agreements

A company-agreement, also called a contract or opportunity, is a contract specifying all the rules that items will be sold under. Each company can have multiple company-agreements. These agreements are created by TBAuctions associates in collaboration with the seller company.

Information about company-agreements, such as the id (UUID) can be retrieved using the Companies API. Company-agreements need to be linked to items to specify under which contract those specific items will be sold. See the "opportunityId" property in the item import endpoint.

Locations

Locations are used for pick-up- or delivery information about the lot. Locations for a given company-agreement can be retrieved using the Companies API Items need a location id (UUID) passed along when they're created. See the "locationId" property in the item import endpoint.

Uploads

The Uploads section in ATLAS is where imports are created, items are added to imports and items are moved into auction buckets. We recommend reviewing your uploads in the ATLAS Portal to verify that your imports and items are coming through correctly. See the Import items 1-by-1 flowchart (pdf) for information on all required and optional steps to take when making uploads to ATLAS.

Imports

Imports are logical batches of items. First an import is created, after which items can be added to it. there are two types of imports: batch and single. Type batch is only used in the ATLAS frontend for batch uploading of items. When creating an import through the API always specify it as type single. This means the import expects individual items to be added.

Items

Items are the main objects that will form a lot on an auction. An item contains all the attributes that will describe the item in the auction. When an item is created it needs the UUID of the imports it's to be added to passed along as property "importId".

Buckets

Buckets contain all items for an auction. A bucket can be filled with one or more entire imports or with selected items from one or multiple imports. Items need to be added to buckets by using the assign items to bucket endpoint.

Categories

Each item belongs to a category. A category contains all information on which attributes can or should be specified for items that belong to that category. Category data changes rarely and can be cached on the client side for a long time.

Categories have a nested structure, for example: the "car" category is a sub-category of the "vehicle" category. You will always create your item under one of the sub-categories. Use the Categories API to retrieve categories and their attributes in order to link items to their relevant category and map the item attributes accordingly.

Media

Media are images that can be linked to items. Use the Inventory Media API to upload Base64 encoded image strings to ATLAS and link them to items.

Auction

In the context of pre-auction, an auction is the set-up for the actual auction. Auctions can not be made through the APIs. All auctions in ATLAS are created by internal employees of TBAuctions. When an auction is created a bucket is automatically created with it. This bucket is then to be filled with items. When the bucket is ready it is to be published.

Orders

Orders are lots that are sold and paid-for. The lots are returned to ATLAS as orders and contain information regarding the buyer and seller of the lot.

An order always has a status depending on its state. The following statuses are used:

  • Processing (New, Downloaded)

  • Sent

  • Delivered

  • Returning

  • Returned

  • Cancelled

  • Completed