Datapel Systems

## 🚀 Theneo

Theneo is the quickest, simplest way to generate high-quality, interactive API docs. Just import your API collection and we'll take care of the rest.

**⚠️ Note:** All of the stated endpoints and sections are for demonstration purposes only. Theneo does not manage payments API. Get sales data, itemize payments, push orders to POS, and more.The Orders API provides a one-stop shop for integrating advanced payment functionality. You can itemize payments with custom line items or catalog objects, send orders to real Point of Sale devices to be fulfilled, and more.In addition, the Orders API allows you to look through all of a seller's previous sales and returns itemization data, customer references, and other information from POS or online transactions.

&lt;img src="https://assets.website-files.com/61f7e03934c23c1dcc9c3cd4/6306089ecc13c15fe0a7e006_Main page_2 (with visual studoi code logo) 2.svg" alt="" height="237" width="322">

### Generate API Documentation

- Build interactive API docs
- Tailor you documentation
- Create and launch quickly
- Update easily within seconds
- Built for everyone
    

# Integrations

Import your collections manually or use our integrations to automatically migrate your work from:

- Swagger
- Postman
- Github
    

[  
](https://www.theneo.io/#)

[  
](https://app.theneo.io/signup)

Datapel API Reference

How it Works

OData Standards Support

OData Web Components

OData Best Practices

🚀 Theneo is the quickest, simplest way to generate high-quality, interactive API docs. Just import your API collection and we'll take care of the rest.

⚠️ Note**:** All of the stated endpoints and sections are for demonstration purposes only. Theneo does not manage payments API. Get sales data, itemize payments, push orders to POS, and more.The Orders API provides a one-stop shop for integrating advanced payment functionality. You can itemize payments with custom line items or catalog objects, send orders to real Point of Sale devices to be fulfilled, and more.In addition, the Orders API allows you to look through all of a seller's previous sales and returns itemization data, customer references, and other information from POS or online transactions.

&lt;img src="https://assets.website-files.com/61f7e03934c23c1dcc9c3cd4/6306089ecc13c15fe0a7e006_Main page_2 (with visual studoi code logo) 2.svg" alt="" height="168" width="200">

### Generate API Documentation

- Build interactive API docs
- Tailor you documentation
- Create and launch quickly
- Update easily within seconds
- Built for everyone
    

# Integrations

Import your collections manually or use our integrations to automatically migrate your work from:

- Swagger
- Postman
- Github

Authentication

Token

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

 *   `given_name`
 *   `family_name`
 *   `company_name`
 *   `email_address`
 *   `phone_number`

Token Refresh

All of the stated endpoints and sections are for demonstration purposes only. Theneo does not manage payments API.  
Get sales data, itemize payments, push orders to POS, and more.

**⚠️ Note:** The Orders API provides a one-stop shop for integrating advanced payment functionality. You can itemize payments with custom line items or catalog objects, send orders to real Point of Sale devices to be fulfilled, and more.

In addition, the Orders API allows you to look through all of a seller's previous sales and returns itemization data, customer references, and other information from POS or online transactions.

&lt;img src="https://media.geeksforgeeks.org/wp-content/cdn-uploads/20200318193845/Top-7-Payment-Gateway-APIs-That-Every-Developer-Must-Know.png">

As an organization, you need to be careful while choosing a payment gateway option. It should be according to the customer’s experience on your websites through to cash flow to online sales. Make sure that you take care of at least 5 things mentioned below while choosing a payment gateway… 

- **Security** should be the topmost priority. Make sure that it should be integrated with the 3D security and comply with the PCI Data Security Standard (PCI DSS).
- **Payout Time** should be less to credit money in your bank account.
- **Integration need to be easy and simple** or it can develop a custom-coded solution for your platform easily.
- **Multiple currencies** should be handled by the payment gateway for the customers using different currencies across the world.

Endpoint Reference

Creates a new order that can include information about products for purchase and settings to apply to the purchase.

Time Stamp

Create Sale Order

Order List

List Items

Audit Events

Product List

Inventory List

Inventory Events

Contact List

Location List

Create Transfer Order

Transfer Order List

Create Purchase Order

Inward Order List

Create Transaction

Theneo Demo TechCrunch

Datapel API

Production

Sandbox

<p class="slate-p" placeholder="Type / for widgets">Welcome to the API Reference for the Datapel Cloud.WMS Inventory Management System (IMS), a powerful and versatile tool designed to streamline the management of order and inventory data for businesses of all sizes. This documentation serves as your comprehensive guide to understanding and use of our API, providing you with the information and resources needed to integrate our system seamlessly into your applications and processes.</p><h3 class="slate-h3"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Why an Inventory Management System Matters</strong></span></h3><p class="slate-p" placeholder="Type / for widgets">Efficient order and inventory management is the cornerstone of successful business operations. Whether you are a small wholesaler, a manufacturing powerhouse, or an e-commerce giant, the ability to track, monitor, and control your inventory is essential for reducing costs, improving customer satisfaction, and driving profitability. Our Inventory Management System is designed to simplify this complex task, offering real-time insights, process automation, and scalability.</p><h3 class="slate-h3"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">What Can You Achieve with Our API</strong></span></h3><p class="slate-p" placeholder="Type / for widgets">The Datapel API opens up many possibilities for developers, businesses, and entrepreneurs seeking to optimise their inventory and order management processes. Here are some potential applications and use cases that can and have been developed using our API:</p><ol class="slate-ol"><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">E-commerce Integration</strong></span> Seamlessly sync your e-commerce platform with our WMS to ensure accurate product availability and pricing on your online store. This leads to fewer out-of-stock situations and enhances the overall shopping experience for your customers.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Warehouse Automation</strong></span> Implement robotic or IoT solutions to automate inventory movement within your warehouses. Our API provides real-time inventory data, enabling robots or devices to make informed decisions about restocking and retrieval.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Multi-Location Management</strong></span> Manage inventory across multiple physical locations, whether they are warehouses, retail stores, or distribution centres. Our API allows you to centralise inventory control and maintain consistency across your network.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Customer and Supplier Collaboration</strong></span> Facilitate better communication with your customers and suppliers by sharing real-time inventory data. Suppliers can use this information to optimise production schedules and ensure timely deliveries, reducing the risk of stockouts. Customers can check availability and account status reducing overall customer servicing costs.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Inventory Forecasting</strong></span> Utilise historical data and predictive analytics to forecast demand and optimise inventory levels. With our API, you can build custom forecasting algorithms and strategies to minimize overstock and understock situations.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Order Fulfillment Automation</strong></span> Create systems that automate order fulfillment processes, ensuring orders are picked, packed, and shipped efficiently, with real-time inventory updates for customers.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Inventory Reporting and Analytics</strong></span> Develop custom dashboards and reporting tools to gain valuable insights into your inventory performance. Track key metrics such as turnover rate, holding costs, and sales velocity.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Inventory Auditing and Compliance</strong></span> Implement auditing solutions that use the IMS API to verify inventory accuracy and compliance with industry regulations. This is especially crucial in sectors with strict quality control requirements.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Inventory Optimization Algorithms</strong></span> Design algorithms that automatically optimise inventory reorder points, safety stock levels, and economic order quantities based on real-time market conditions.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Retail Shelf Management</strong></span> Optimise the placement of products on store shelves by utilising our API to ensure high-demand items are always readily available, leading to increased sales.</div></li></ol><p class="slate-p" placeholder="Type / for widgets">The Cloud.WMS API empowers you to take control of your inventory and order management processes and drive operational excellence across your business. Whether you are looking to enhance the efficiency of your supply chain, boost customer satisfaction, or make data-driven decisions, our API is your gateway to achieving these objectives with precision and ease. 
</p><p class="slate-p" placeholder="Type / for widgets">In this API Reference, you will find detailed documentation, code examples, and best practices to help you harness the full potential of our Inventory Management System API.</p><p class="slate-p" placeholder="Type / for widgets">

</p><p class="slate-p" placeholder="Type / for widgets"><a href="https://www.theneo.io/#" target="_blank"></a></p><p class="slate-p" placeholder="Type / for widgets"><a href="https://app.theneo.io/signup" target="_blank"></a></p>

Welcome to the API Reference for the Datapel Cloud.WMS Inventory Management System (IMS), a powerful and versatile tool designed to streamline the management of order and inventory data for businesses of all sizes. This documentation serves as your comprehensive guide to understanding and use of our API, providing you with the information and resources needed to integrate our system seamlessly into your applications and processes.

Why an Inventory Management System Matters

Efficient order and inventory management is the cornerstone of successful business operations. Whether you are a small wholesaler, a manufacturing powerhouse, or an e-commerce giant, the ability to track, monitor, and control your inventory is essential for reducing costs, improving customer satisfaction, and driving profitability. Our Inventory Management System is designed to simplify this complex task, offering real-time insights, process automation, and scalability.

The Datapel API opens up many possibilities for developers, businesses, and entrepreneurs seeking to optimise their inventory and order management processes. Here are some potential applications and use cases that can and have been developed using our API:

The Cloud.WMS API empowers you to take control of your inventory and order management processes and drive operational excellence across your business. Whether you are looking to enhance the efficiency of your supply chain, boost customer satisfaction, or make data-driven decisions, our API is your gateway to achieving these objectives with precision and ease. 


In this API Reference, you will find detailed documentation, code examples, and best practices to help you harness the full potential of our Inventory Management System API.

<h3 class="slate-h3">Retrieving Data</h3><p class="slate-p slate-indent-0" style="margin-left:0px" placeholder="Type / for widgets"><span style="background-color:rgb(255, 255, 255);color:rgb(90, 90, 90);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(90, 90, 90);font-size:14px" class="slate-backgroundColor">Use the HTTP GET method to retrieve data from your workspace via endpoint resources. This includes both lists and individual records. For example, you would use the GET method to retrieve a list of sales orders made in a particular month, or the contact details of a customer. </span></span></p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">Successful responses return with a <a href="https://developer.xero.com/documentation/api/accounting/responsecodes#common-response-codes" target="_blank">HTTP 200</a> status code</div></li><li class="slate-li"><div style="position:relative">By default all successful responses on the Datapel API are returned as JSON.</div></li><li class="slate-li"><div style="position:relative">The API requires a security domain or scope to be provided with TOKEN requests and REFRESH, for public api resources use <span style="color:#6C9EEB" class="slate-color"><strong style="color:#6C9EEB" class="slate-bold">pub</strong></span>.  </div></li><li class="slate-li"><div style="position:relative">Forms and Reports can also be returned in PDF format ensure you apply the correct content type header when required.</div></li><li class="slate-li"><div style="position:relative">Example GET request for a particular product would look like this → <a href="https://api2.datapel.net/api.datapel/v2.0/myaccount/product?34" target="_blank">https://api2.datapel.net/api.datapel/v2.0/pub/product?34</a></div></li></ul><h3 class="slate-h3">JSON responses and date formats</h3><p class="slate-p" placeholder="Type / for widgets">By default JSON formatted responses are returned, be sure to use the http header “application/json” when making a request.</p><p class="slate-p" placeholder="Type / for widgets">Any Date returned in JSON datasets is UTC format represented as <strong class="slate-bold">YYYY-MM-DDTHH:mm:SS</strong>, for example ‘<em style="font-size:11pt" class="slate-italic">2009-04-29T10:12:20’. </em></p><p class="slate-p" placeholder="Type / for widgets">In order to reduce overall data transfer requirements a record level <span style="color:#1155CB" class="slate-color">TIMESTAMP</span> is typically available with format ‘2<em class="slate-italic">021-10-01 16:35:03’ </em>indicating the time this record was <span style="color:#FE9900" class="slate-color">last modified</span>.</p><h3 class="slate-h3">Filtering Data </h3><p class="slate-p slate-indent-0" style="margin-left:0px" placeholder="Type / for widgets">The Datapel API uses the OData standard as the syntax allowing queries of specific data records. By using OData filter queries, you can obtain specific subsets of data, reducing the amount of unnecessary information and enhancing the performance of your workflows.

When using filters, you can use comparison operators like <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">eq</span> for <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">equals</span>, <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">ne</span> for <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">not equals</span>, and so on. You can also use logical operators such as <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">and</span>, <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">or</span>, and <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">not</span> to combine multiple conditions. Additionally, there are functions to refine string-based searches. For example, <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">startswith(fieldName,’string’)</span> checks if a field starts with a specified string, <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">endswith(fieldName,’string’)</span> checks if it ends with one, and <span style="background-color:transparent;font-size:20px" class="slate-backgroundColor">substringof(‘string’,fieldName)</span> verifies if a field contains a particular substring.</p><p class="slate-p slate-indent-0" style="margin-left:0px" placeholder="Type / for widgets">To explore the syntax and example queries review the OData Standards Support section of this reference guide.</p><h3 class="slate-h3">Pagination</h3><p class="slate-p slate-indent-0" style="margin-left:0px" placeholder="Type / for widgets">A single HTTP GET request can return at most 500 records. This is reasonable because most HTTP clients have a timeout limit of 2 - 5 minutes. They do not allow transactions to wait more than that. A request running longer than the limit gets an HTTP timeout error. Therefore, it is often required to tune complex queries and lower the data size for them to complete within the timeout restriction. Long running queries can also degrade server response times to other users and tenants so its best practice to do smaller queries more often than large one off data requests</p><p class="slate-p" placeholder="Type / for widgets">The OData API provides several pagination options for query results.</p><p class="slate-p" placeholder="Type / for widgets">Client-side pagination uses query options on the client side to create an offset that restricts the amount of data returned from the server.</p><p class="slate-p" placeholder="Type / for widgets">A client-side pagination query can be made using the following URI parameters:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">The $top parameter indicates the number of records to return in the batch. The default and maximum number is 500 records.</div></li><li class="slate-li"><div style="position:relative">The $skip parameter indicates the number of records in the full data set to skip before fetching data.</div></li></ul><p class="slate-p" placeholder="Type / for widgets">For example, a query with $skip=2000&amp;$top=500 returns the fifth page of data where the page size is 500.</p><p class="slate-p" placeholder="Type / for widgets"><span style="color:#666666" class="slate-color"><strong style="color:#666666" class="slate-bold">Advantages</strong></span></p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">Faster initial page load</div></li><li class="slate-li"><div style="position:relative">It works well with OData compliant list and table web controls to fetch records on demand. DevExtreme UI controls from <a href="https://js.devexpress.com/" target="_self">DevExpress</a> automatically change the $skip value in order to scroll through the data set.</div></li><li class="slate-li"><div style="position:relative">It allows reverse scrolling by decreasing $skip values. This allows UI controls to avoid buffering all data as the user scrolls up and down.</div></li></ul><p class="slate-p" placeholder="Type / for widgets"><span style="color:#666666" class="slate-color"><strong style="color:#666666" class="slate-bold">Considerations when using OData pagination</strong></span></p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">For each page, the query is re-executed and then moves forward through the data set to reach the specified $skip value. Not only is this inefficient but also it can lead to unstable results. The data set could be changing due to simultaneous creating, updating, or deleting of the data. Conversely, most modern databases implement caching and will generally store prior query data so this does not present as a major limitation or issue.</div></li><li class="slate-li"><div style="position:relative">If a record is inserted on a prior page after it has been read, it shifts the data set to the right, resulting the last record from the previous page to be pushed into the current page. This causes the page to be read again because the $skip value of the current page is one record too small, resulting in duplicates in the total data set. You can avoid this issue using $orderBy=TimeStamp to push newly created records to the end of the data set.</div></li><li class="slate-li"><div style="position:relative">If a record is deleted from a prior page after it has been read, it shifts the data set to the left. The first record of the current page is lost because the $skip value of the current page is one record too large. There’s no good workaround when dealing with concurrent hard deletes from the data set. Note these potential data loss issues make &quot;last modified since&quot; queries especially unreliable. If a record is lost in a query, it can only be picked up by a later attempt after it&apos;s modified.</div></li></ul><p class="slate-p" placeholder="Type / for widgets">Most queries will return a total record count which allows your request to select a exact page number, and identify the total number of pages to retrieve. Alternatively continue to iterate over the query using the $skip keyword until no records or less than 500 (page maximum) are returned.</p><p class="slate-p" placeholder="Type / for widgets">











</p><p class="slate-p" placeholder="Type / for widgets"></p>

Use the HTTP GET method to retrieve data from your workspace via endpoint resources. This includes both lists and individual records. For example, you would use the GET method to retrieve a list of sales orders made in a particular month, or the contact details of a customer. 

By default JSON formatted responses are returned, be sure to use the http header “application/json” when making a request.

Any Date returned in JSON datasets is UTC format represented as 

In order to reduce overall data transfer requirements a record level 

The Datapel API uses the OData standard as the syntax allowing queries of specific data records. By using OData filter queries, you can obtain specific subsets of data, reducing the amount of unnecessary information and enhancing the performance of your workflows.

When using filters, you can use comparison operators like 

, and so on. You can also use logical operators such as 

 to combine multiple conditions. Additionally, there are functions to refine string-based searches. For example, 

 checks if a field starts with a specified string, 

 verifies if a field contains a particular substring.

To explore the syntax and example queries review the OData Standards Support section of this reference guide.

A single HTTP GET request can return at most 500 records. This is reasonable because most HTTP clients have a timeout limit of 2 - 5 minutes. They do not allow transactions to wait more than that. A request running longer than the limit gets an HTTP timeout error. Therefore, it is often required to tune complex queries and lower the data size for them to complete within the timeout restriction. Long running queries can also degrade server response times to other users and tenants so its best practice to do smaller queries more often than large one off data requests

The OData API provides several pagination options for query results.

Client-side pagination uses query options on the client side to create an offset that restricts the amount of data returned from the server.

A client-side pagination query can be made using the following URI parameters:

For example, a query with $skip=2000&$top=500 returns the fifth page of data where the page size is 500.

Considerations when using OData pagination

Most queries will return a total record count which allows your request to select a exact page number, and identify the total number of pages to retrieve. Alternatively continue to iterate over the query using the $skip keyword until no records or less than 500 (page maximum) are returned.

OData is a way to query data sources over the web using a standard syntax. It allows requesting of specific data columns with filter expressions to return required data sets typically in JSON format. Because the OData specification is standardised and ISO/IEC approved, you can theoretically use any OData compliant data source and it will respond in the same way to an OData formatted query.

Parameters are made up of the various OData functions for selecting and filtering entities.

These parameters are chained together after the entity using '&':

Filters allow you to reduce the data set by specifying a field and a requirement. There are 2 formats for filter:

The correct format to use depends on the operator you are using.

There are other more specific expressions which you can find at the 

Filters can be chained together internally with 'and' or 'or' to create more complex expressions:

The orderBy function allows you to specify a sort for your data. The syntax for this is:

Direction is either ascending or descending as shown in these examples:

Top and Skip tend to go hand in hand. Top can be used to limit the number of records returned, while skip allows you to start from further down your list of results. In order to create PAGED results use the top keyword to specify the number of records and skip * page * number of records per page to get the a particular page in the result set.

Datapel API Supports basic OData syntax for keywords 

select, filter, skip, top, order by and apply. 

Aggregations using Odata apply query option is supported.

<p class="slate-p" placeholder="Type / for widgets"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">To simplify web application development OData compliant web components can bind directly to the API endpoint services. For example the DevExpress DevExtreme javascript visual components have OData 2.0 and 4.0 compatible controls. DevExtreme supports a multitude of frameworks including KnockOut, Angular, React and others. The primary adapter for the API was selected as OData to align with the Microsoft Web Services Stack and the ability to standardise the filtering and selection syntax that simplifies SQL translation.</span></span>

For general information on OData compliance <a href="https://www.odata.org/" target="_blank">https://www.odata.org/</a></p><p class="slate-p" placeholder="Type / for widgets">For more information on DevExtreme Web Components please refer to the following <a href="https://js.devexpress.com/" target="_blank">https://js.devexpress.com/</a></p><p class="slate-p" placeholder="Type / for widgets">On OData refer to <a href="https://js.devexpress.com/Documentation/Guide/Data_Binding/Specify_a_Data_Source/OData/" target="_blank">https://js.devexpress.com/Documentation/Guide/Data_Binding/Specify_a_Data_Source/OData/</a></p><p class="slate-p" placeholder="Type / for widgets">For specific connector declaration visit <a href="https://js.devexpress.com/Documentation/ApiReference/Data_Layer/ODataStore/" target="_blank">https://js.devexpress.com/Documentation/ApiReference/Data_Layer/ODataStore/</a></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

To simplify web application development OData compliant web components can bind directly to the API endpoint services. For example the DevExpress DevExtreme javascript visual components have OData 2.0 and 4.0 compatible controls. DevExtreme supports a multitude of frameworks including KnockOut, Angular, React and others. The primary adapter for the API was selected as OData to align with the Microsoft Web Services Stack and the ability to standardise the filtering and selection syntax that simplifies SQL translation.



For general information on OData compliance 

For more information on DevExtreme Web Components please refer to the following 

For specific connector declaration visit 

<p class="slate-p" placeholder="Type / for widgets"><span style="color:rgb(51, 51, 51);font-size:16px" class="slate-color">Read and follow the best practices in this topic for optimal OData API performance and a better user experience.</span>
</p><table class="slate-table"><colgroup><col style="width:28.293063133281372%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Query Only Modified Records</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Instead of querying all records, query only the records that have been modified since your last execution for integration use cases. </p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:28.83865939204988%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Avoid Frequent Query Runs to Get Real-Time Results</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Repeating queries in much less than one hour will consume too much API resource, which may be throttled in the future. In extreme cases, you may even be denied of service because of frequent queries, especially ones that require heavy backend processing.</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:28.994544037412318%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Avoid Excessive Queries for Single Records</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Querying records one at a time doesn’t take advantage of database optimisation capabilities. Singleton queries are often used to perform in-memory joins and should be avoided whenever possible. For example:</p><pre class="slate-CodeBlockElement slate-code_block"><div contenteditable="false"><div ><span aria-live="polite" aria-atomic="false" aria-relevant="additions text" ></span><div ><div ><div >Select...</div><div ><div  style="display:inline-block"><input type="text" autoCapitalize="none" autoComplete="off" autoCorrect="off" id="react-select-211-input" spellcheck="false" tabindex="0" value="" aria-autocomplete="list" style="box-sizing:content-box;width:1px;label:input;background:0;border:0;font-size:inherit;opacity:1;outline:0;padding:0;color:inherit"/><div style="position:absolute;top:0;left:0;visibility:hidden;height:0;overflow:scroll;white-space:pre"></div></div></div></div><div ><span ></span><div  aria-hidden="true"><svg height="20" width="20" viewBox="0 0 20 20" aria-hidden="true" focusable="false" ><path d="M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z"></path></svg></div></div></div></div></div><code class="keep-markup drop-tokens"><div class="slate-code_line">&amp;$filter= &lt;key&gt; eq &lt;keyvalue&gt;</div></code></pre></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:29.228371005455962%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Use $select to Get Only the Properties You Need</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Without the $select query option, a query returns all available properties of an entity. For better performance, we recommend that you add the $select system query option to specify only the properties you need.</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:29.61808261886204%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Keep Transactions Simple to Avoid Poor Performance</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Poor performance is often a sign of misuse of APIs. As a rule of thumb, always keep your transactions simple.</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:30.00779423226812%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Sync Frequently and Sync Only Delta Changes</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Full data sync can lead to high resource consumption and poor performance. Instead of doing a full data sync intermittently, schedule more frequent data sync but limit the scope to only delta changes.</p><p class="slate-p" placeholder="Type / for widgets">Keep in mind the current limits for the public api are <strong class="slate-bold">10,000 requests per day</strong> with not more than <strong class="slate-bold">2 requests per second.</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:30.319563522992986%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Implement Retry Logic Properly</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Retry logic can help recover failed transactions due to Internet connectivity or backend server issues, but retry must be attempted with caution based on the type of HTTP error.</p><p class="slate-p" placeholder="Type / for widgets">In all cases, wait at least between 1 to 5 minutes before attempting a retry. Excessive immediate retry can cause denial of service giving little time for the server to recover.</p><p class="slate-p" placeholder="Type / for widgets">Retry no more than 5 times before abandoning your task. </p><p class="slate-p" placeholder="Type / for widgets">Error types eligible for retry:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">Note <strong class="slate-bold">503 Service Not Available</strong> can occur when a server is overloaded. It can also occur during maintenance periods. Avoid running queries during these published maintenance periods.</div></li><li class="slate-li"><div style="position:relative">HTTP timeout errors can be retried only if your client timeout matches the infrastructure timeout of 5 minutes. If you retry a timeout before this period, you&apos;re stacking transactions on top of each other and performing a possible denial-of-service attack.</div></li><li class="slate-li"><div style="position:relative">HTTP connection reset error and no response are given from server side.</div></li><li class="slate-li"><div style="position:relative"><strong class="slate-bold">429 Too Many Requests </strong>can occur if you have reached your quota or making too many concurrent requests. In this case you should check for response to see if your Total Request count exceeds the daily limit, or if this is a throttling response. Typically wait a few seconds and try the request again.</div></li></ul><pre class="slate-CodeBlockElement slate-code_block"><div contenteditable="false"><div ><span aria-live="polite" aria-atomic="false" aria-relevant="additions text" ></span><div ><div ><div >Select...</div><div ><div  style="display:inline-block"><input type="text" autoCapitalize="none" autoComplete="off" autoCorrect="off" id="react-select-212-input" spellcheck="false" tabindex="0" value="" aria-autocomplete="list" style="box-sizing:content-box;width:1px;label:input;background:0;border:0;font-size:inherit;opacity:1;outline:0;padding:0;color:inherit"/><div style="position:absolute;top:0;left:0;visibility:hidden;height:0;overflow:scroll;white-space:pre"></div></div></div></div><div ><span ></span><div  aria-hidden="true"><svg height="20" width="20" viewBox="0 0 20 20" aria-hidden="true" focusable="false" ><path d="M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z"></path></svg></div></div></div></div></div><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
 &quot;status&quot; : &quot;error&quot;, 
 &quot;message&quot; : &quot;Too many requests&quot;, 
 &quot;data&quot; : &quot;Total Requests 12000&quot;, 
  &quot;error&quot; : {
  &quot;code&quot;:&quot;429&quot;,
  &quot;message&quot;: { &quot;lang&quot;:&quot;en-us&quot;, 
       &quot;value&quot;: &quot;Request rate must not exceed 1 per second or 10,000 per 24 hours.&quot;  
      } 
  } 
}</div></code></pre><p class="slate-p" placeholder="Type / for widgets">Errors for which retry shouldn’t be attempted:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative">401 Authentication Failed error. You have provided incorrect credentials and retrying doesn&apos;t help.</div></li><li class="slate-li"><div style="position:relative">404 Not Found error. You can&apos;t recover something that doesn’t exist.</div></li><li class="slate-li"><div style="position:relative">400 Bad Request error. This error can occur for edit operations that are missing required data or have incorrect formats.</div></li><li class="slate-li"><div style="position:relative">Do not retry POST operations without doing a GET request to check if the payload was accepted with a failed response. Otherwise rePOSTing can result in duplicate data.</div></li></ul></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><table class="slate-table"><colgroup><col style="width:30.631332813717847%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">Avoid Excessive Client Multithreading</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">To prevent server overloads and ensure high availability, we recommend a limiting the use of concurrent API requests for any company instance. If you require a real time, high duty integration you may need to discuss and <strong class="slate-bold">Enterprise API</strong> option which removes daily quota and rate limits.</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><p class="slate-p" placeholder="Type / for widgets">













</p>

Read and follow the best practices in this topic for optimal OData API performance and a better user experience.

<h2 class="slate-h2">Bearer Token Authentication</h2><p class="slate-p" placeholder="Type / for widgets">Datapel API version 2.0 uses Bearer Token Authentication, a crucial security mechanism that safeguards our API endpoints and ensures secure communication between clients apps and our API servers. This section describes what Bearer Token Authentication is, how it works, and how to manage secure API access.</p><p class="slate-p" placeholder="Type / for widgets">Bearer Token Authentication is a widely adopted method for securing APIs, relied upon by countless applications and services across the internet. It offers a robust, standardized approach to verifying the identity of clients attempting to access an API resource. With Bearer Token Authentication, you can establish trust between the API server and its clients, ensuring that only authorized parties gain access while keeping unauthorized users at out.</p><p class="slate-p" placeholder="Type / for widgets">In this documentation reference, we will cover the following key topics:</p><ol class="slate-ol"><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Understanding Bearer Tokens:</strong></span> Get acquainted with the concept of bearer tokens, their structure, and how they function as credentials for authenticating your API requests.</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Generation and Management:</strong></span> Learn how we generate, issue, and manage bearer tokens securely, with best practice token lifetimes and refresh mechanisms.</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Authentication Flow:</strong></span> Understand step-by-step the process of how client apps present bearer tokens in API requests, and how our API server validates these tokens to grant or deny access.</div></li></ol><p class="slate-p" placeholder="Type / for widgets">The following sections describes our implementation of the Bearer Token Authentication process.</p><p class="slate-p" placeholder="Type / for widgets"></p><h1 class="slate-h1">Understanding Bearer Tokens</h1><p class="slate-p" placeholder="Type / for widgets">Bearer Tokens are at the heart of Bearer Token Authentication, serving as the digital keys that grant access to API resources. </p><h3 class="slate-h3">What is a Bearer Token?</h3><p class="slate-p" placeholder="Type / for widgets">A Bearer Token is a type of access token used in authentication protocols, such as OAuth 2.0 and OpenID Connect. It is a string of characters, typically represented as a long, random alphanumeric sequence. Bearer Tokens act as credentials that a client (usually a user or application) presents to an API server when making a request for a protected resource.</p><h3 class="slate-h3">How Do Bearer Tokens Work?</h3><p class="slate-p" placeholder="Type / for widgets">Bearer Tokens operate on a straightforward principle: possession of the token equals access. When a client wishes to access a protected resource via an API, it includes the Bearer Token in the request, typically within the HTTP Authorization header. The server receives the token, validates it, and if the token is valid and not expired, it grants access to the requested resource.</p><h3 class="slate-h3">Stateless Authentication</h3><p class="slate-p" placeholder="Type / for widgets">One of the advantages of Bearer Tokens is their statelessness. Unlike session-based authentication, where server-side state is maintained for each user, Bearer Tokens require no server-side storage of session data. This makes them highly scalable and suitable for stateless API architectures, such as RESTful APIs.</p><h3 class="slate-h3">Security Considerations</h3><p class="slate-p" placeholder="Type / for widgets">While Bearer Tokens offer an efficient way to authenticate API requests, they come with security responsibilities. Since anyone in possession of a Bearer Token can access the protected resources, it is crucial to protect these tokens from theft and misuse. Security measures include token encryption, short token lifetimes, and token revocation mechanisms.</p><h3 class="slate-h3">Token Payload</h3><p class="slate-p" placeholder="Type / for widgets">Bearer Tokens often contain a payload that carries information about the client or user, such as user roles or permissions. This payload can help your API server make access control decisions based on the token&apos;s content.</p><p class="slate-p" placeholder="Type / for widgets">In summary, Bearer Tokens represent the authorization credentials clients use to access an APIs protected resources. Understanding their structure, how they are transmitted, and their security implications is fundamental to implementing secure and efficient API based Application. </p><p class="slate-p" placeholder="Type / for widgets"></p><h1 class="slate-h1">Token Generation and Management</h1><p class="slate-p" placeholder="Type / for widgets">Token generation and management are critical aspects of Bearer Token Authentication. To ensure the security of the Datapel API our tokens are 256 bit encrypted and have a limited life span of 30 minutes. A refresh token is provided to allow trust renewal by following the Refresh Authentication flow.</p><p class="slate-p" placeholder="Type / for widgets">The Bearer Token Authorization flow involves a series of steps that allow a client (such as a user or application) to authenticate itself and gain access to protected resources on our API. This flow is based on the OAuth 2.0 framework and is widely used for securing APIs. Here&apos;s a step-by-step breakdown of the typical Bearer Token Authorization flow:</p><ol class="slate-ol"><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Client Registration (Optional):</strong></span> In most cases, our clients need to be registered with API access to our server. During registration, you will receive an API key and secret, which are used to identify and authenticate your application. This step is commonly seen in OAuth 2.0.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Authentication Request:</strong></span> Your app initiates the authentication process by sending a request to our API TOKEN endpoint. 
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Issuance:</strong></span> The API server processes the token request, verifies identity, and, if everything checks out, issues an access token. This access token is a bearer token, and its purpose is to prove the client&apos;s authorization to access protected resources. Included in the token is a refresh token which allows renewed trust access tokens without needing the initial API key or User credentials.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Usage:</strong></span> The client includes the access token in the <span style="color:var(--tw-prose-code);font-size:0.875em" class="slate-color"><code style="color:var(--tw-prose-code);font-size:0.875em" class="slate-code"><strong style="color:var(--tw-prose-code);font-size:0.875em" class="slate-bold">Authorization</strong></code></span> header of its API requests, using the &quot;Bearer&quot; prefix (e.g., &quot;Bearer [access token]&quot;). This token is what grants the client access to the API resources.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Validation:</strong></span> When the API server receives a request with an access token, it validates the token to ensure it&apos;s genuine, unexpired, and has the necessary permissions to access the requested resource. This step often involves checking the token&apos;s digital signature, expiration time, and scope.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Access Control:</strong></span> If the token is valid, the API server grants the client access to the requested resource. Access control decisions may also be based on the user&apos;s identity and the permissions associated with the token.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Revocation (Optional):</strong></span> To maintain security, tokens can be revoked by either the client or the authorization server when they are no longer needed or if they are compromised.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Token Expiration and Refresh (Optional):</strong></span> Access tokens have a limited lifetime. Your application can request a new access token using a refresh token if the original token expires. This helps maintain the session&apos;s longevity while minimizing security risks.
</div></li><li class="slate-li"><div style="position:relative"><span style="color:var(--tw-prose-bold)" class="slate-color"><strong style="color:var(--tw-prose-bold)" class="slate-bold">Logging and Monitoring:</strong></span> Our API has backend monitoring and logging and if required we can assist with troubleshooting any access issues you may experience by reviewing request history.</div></li></ol><p class="slate-p" placeholder="Type / for widgets">

<span style="background-color:rgb(52, 53, 65);color:rgb(255, 255, 255);font-size:medium" class="slate-color"><span style="background-color:rgb(52, 53, 65);color:rgb(255, 255, 255);font-size:medium" class="slate-backgroundColor">


</span></span></p><p class="slate-p" placeholder="Type / for widgets">




</p><p class="slate-p" placeholder="Type / for widgets"></p>

Datapel API version 2.0 uses Bearer Token Authentication, a crucial security mechanism that safeguards our API endpoints and ensures secure communication between clients apps and our API servers. This section describes what Bearer Token Authentication is, how it works, and how to manage secure API access.

Bearer Token Authentication is a widely adopted method for securing APIs, relied upon by countless applications and services across the internet. It offers a robust, standardized approach to verifying the identity of clients attempting to access an API resource. With Bearer Token Authentication, you can establish trust between the API server and its clients, ensuring that only authorized parties gain access while keeping unauthorized users at out.

In this documentation reference, we will cover the following key topics:

The following sections describes our implementation of the Bearer Token Authentication process.

Bearer Tokens are at the heart of Bearer Token Authentication, serving as the digital keys that grant access to API resources. 

A Bearer Token is a type of access token used in authentication protocols, such as OAuth 2.0 and OpenID Connect. It is a string of characters, typically represented as a long, random alphanumeric sequence. Bearer Tokens act as credentials that a client (usually a user or application) presents to an API server when making a request for a protected resource.

Bearer Tokens operate on a straightforward principle: possession of the token equals access. When a client wishes to access a protected resource via an API, it includes the Bearer Token in the request, typically within the HTTP Authorization header. The server receives the token, validates it, and if the token is valid and not expired, it grants access to the requested resource.

One of the advantages of Bearer Tokens is their statelessness. Unlike session-based authentication, where server-side state is maintained for each user, Bearer Tokens require no server-side storage of session data. This makes them highly scalable and suitable for stateless API architectures, such as RESTful APIs.

While Bearer Tokens offer an efficient way to authenticate API requests, they come with security responsibilities. Since anyone in possession of a Bearer Token can access the protected resources, it is crucial to protect these tokens from theft and misuse. Security measures include token encryption, short token lifetimes, and token revocation mechanisms.

Bearer Tokens often contain a payload that carries information about the client or user, such as user roles or permissions. This payload can help your API server make access control decisions based on the token's content.

In summary, Bearer Tokens represent the authorization credentials clients use to access an APIs protected resources. Understanding their structure, how they are transmitted, and their security implications is fundamental to implementing secure and efficient API based Application. 

Token generation and management are critical aspects of Bearer Token Authentication. To ensure the security of the Datapel API our tokens are 256 bit encrypted and have a limited life span of 30 minutes. A refresh token is provided to allow trust renewal by following the Refresh Authentication flow.

The Bearer Token Authorization flow involves a series of steps that allow a client (such as a user or application) to authenticate itself and gain access to protected resources on our API. This flow is based on the OAuth 2.0 framework and is widely used for securing APIs. Here's a step-by-step breakdown of the typical Bearer Token Authorization flow:

<p class="slate-p" placeholder="Type / for widgets"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">Submit User or Developer App credentials for Authentication, if successful returns a Bearer Token. Also used to refresh tokens to allow continued API access without requiring user credentials to be re-validated. Tokens use the JWT form and more information on token structure can be found at </span></span><a href="https://jwt.io/introduction" target="_blank">https://jwt.io/introduction</a><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">. </span></span></p><p class="slate-p" placeholder="Type / for widgets"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">To access an endpoint service a valid token must be passed in the Authorization Header parameter.</span></span></p><h3 class="slate-h3">Parameters</h3><p class="slate-p" placeholder="Type / for widgets">Parameters required will depend on the <span style="color:green" class="slate-color">grant_type</span>. When getting an initial token you must pass <span style="color:green" class="slate-color">grant_type</span> = <strong class="slate-bold">password</strong>, or to renew the access token you must pass <span style="color:green" class="slate-color">grant_type</span> = <strong class="slate-bold">refresh_token</strong>.</p><h3 class="slate-h3">Using grant_type=password</h3><p class="slate-p" placeholder="Type / for widgets">In the authentication life-cycle this is the first action your application should take in order to establish a trusted connection with our API. The <span style="color:#38761D" class="slate-color"><strong style="color:#38761D" class="slate-bold">token</strong></span> endpoint requires a username (api-key), password (api-secret), <span style="color:green" class="slate-color">grant_type</span>=password, and a scope parameter.  As a general rule you should never store any user provided credentials once granted a valid token and refresh_token, by doing so you can avoid credential theft and maintain a secure trust environment. Exceptions to this include server-side applications where access is direct to the application API over secure HTTPS connection. In any case credentials should never be stored as plain text and should be encrypted using industry standard protocols. </p><p class="slate-p" placeholder="Type / for widgets">You must provide at all the following values in your request to this endpoint:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative"><code class="slate-code">username</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">password</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">grant_type</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">scope</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">authorization</code></div></li></ul><h3 class="slate-h3">Sample Code</h3><p class="slate-p" placeholder="Type / for widgets">Here is a sample token request using jQuery.</p><pre class="slate-CodeBlockElement slate-code_block"><div contenteditable="false"><div ><span aria-live="polite" aria-atomic="false" aria-relevant="additions text" ></span><div ><div ><div >Select...</div><div ><div  style="display:inline-block"><input type="text" autoCapitalize="none" autoComplete="off" autoCorrect="off" id="react-select-21-input" spellcheck="false" tabindex="0" value="" aria-autocomplete="list" style="box-sizing:content-box;width:1px;label:input;background:0;border:0;font-size:inherit;opacity:1;outline:0;padding:0;color:inherit"/><div style="position:absolute;top:0;left:0;visibility:hidden;height:0;overflow:scroll;white-space:pre"></div></div></div></div><div ><span ></span><div  aria-hidden="true"><svg height="20" width="20" viewBox="0 0 20 20" aria-hidden="true" focusable="false" ><path d="M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z"></path></svg></div></div></div></div></div><code class="keep-markup drop-tokens"><div class="slate-code_line">$.ajax({</div><div class="slate-code_line">  url: &apos;https://api2.datapel.net/api.datapel/v2.0/token&apos;,</div><div class="slate-code_line">  type: &apos;POST&apos;,</div><div class="slate-code_line">  headers: {</div><div class="slate-code_line">    &apos;Authorization&apos;: &apos;Bearer&apos;,</div><div class="slate-code_line">    &apos;Content-Type&apos;: &apos;application/json&apos;,</div><div class="slate-code_line">    &apos;grant_type&apos;: &apos;password&apos;,</div><div class="slate-code_line">    ‘username’: &apos;api-username&apos;,</div><div class="slate-code_line">    &apos;password&apos;: &apos;api-secret&apos;,</div><div class="slate-code_line">    &apos;scope&apos;: &apos;pub&apos;</div><div class="slate-code_line">  }),</div><div class="slate-code_line">  success: function (response) {</div><div class="slate-code_line">    // Handle the response here
</div><div class="slate-code_line">    console.log(response);</div><div class="slate-code_line">  },</div><div class="slate-code_line">  error: function (error) {</div><div class="slate-code_line">    // Handle errors here
</div><div class="slate-code_line">    console.error(error);</div><div class="slate-code_line">  }</div><div class="slate-code_line">});</div></code></pre><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

Submit User or Developer App credentials for Authentication, if successful returns a Bearer Token. Also used to refresh tokens to allow continued API access without requiring user credentials to be re-validated. Tokens use the JWT form and more information on token structure can be found at 

To access an endpoint service a valid token must be passed in the Authorization Header parameter.

. When getting an initial token you must pass 

, or to renew the access token you must pass 

In the authentication life-cycle this is the first action your application should take in order to establish a trusted connection with our API. The 

 endpoint requires a username (api-key), password (api-secret), 

=password, and a scope parameter.  As a general rule you should never store any user provided credentials once granted a valid token and refresh_token, by doing so you can avoid credential theft and maintain a secure trust environment. Exceptions to this include server-side applications where access is direct to the application API over secure HTTPS connection. In any case credentials should never be stored as plain text and should be encrypted using industry standard protocols. 

You must provide at all the following values in your request to this endpoint:

Here is a sample token request using jQuery.

Authorization

grant_type

Content-Type

username

password

scope

access_token

token_type

Valid Token time is 30 minutes from request

expires_in

userName

Only required if userName is associated with multiple workspaces or scopes - if not provided the default/first tenant will be assumed

tenantKey

The endpoint resource domain this user is authorised to access, for general api usage specify pub_*

JWT encoded refresh token valid for 3 months

refresh_token

JSON array of tenantKeys with workspace domain information

tenants

<p class="slate-p" placeholder="Type / for widgets">Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope. <strong style="font-size:15px" class="slate-bold">Access Tokens</strong> have a limited lifespan and need to be re-issued on a regular basis. The refresh_token is the mandatory credential used to obtain new access tokens. 
</p><h3 class="slate-h3">Parameters</h3><p class="slate-p" placeholder="Type / for widgets">To renew the access token you must pass <span style="color:green" class="slate-color">grant_type</span> = <strong class="slate-bold">refresh_token. </strong><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">This option requires at minimum a valid or expired access_token, refresh_token, </span></span><span style="background-color:rgb(255, 255, 255);color:green;font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:green;font-size:14px" class="slate-backgroundColor">grant_type</span></span><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor">, and scope parameter. The refresh_token option allows you to update an access token without a username and password. If you are connecting to a specific tenant then you MUST INCLUDE the </span></span><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor"><strong style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-bold">tenantKey</strong></span></span><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:rgb(106, 110, 113);font-size:14px" class="slate-backgroundColor"> within the parameters.</span></span>

You must provide at all the following values in your request to this endpoint:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative"><code class="slate-code">Authorization</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">refresh_token</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">grant_type</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">scope</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">tenantKey (optional)</code></div></li></ul><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope. 

 have a limited lifespan and need to be re-issued on a regular basis. The refresh_token is the mandatory credential used to obtain new access tokens. 


To renew the access token you must pass 

This option requires at minimum a valid or expired access_token, refresh_token, 

, and scope parameter. The refresh_token option allows you to update an access token without a username and password. If you are connecting to a specific tenant then you MUST INCLUDE the 



You must provide at all the following values in your request to this endpoint:

new JWT encoded token valid for 30 minutes

new JWT encoded refresh token valid for 3 months

<p>Welcome to the Endpoint Resources Listing section of our API reference. This comprehensive guide provides a detailed overview of all available endpoints and resources within our API. Whether you're a developer looking to integrate our services into your application or an experienced user seeking to explore the capabilities of our API, you'll find everything you need to get started and make the most of our platform.</p>

Welcome to the Endpoint Resources Listing section of our API reference. This comprehensive guide provides a detailed overview of all available endpoints and resources within our API. Whether you're a developer looking to integrate our services into your application or an experienced user seeking to explore the capabilities of our API, you'll find everything you need to get started and make the most of our platform.

In this section, you will find a structured and organized list of API endpoints, each accompanied by a description of its purpose and usage. We have designed our API with simplicity and flexibility in mind, ensuring that you can efficiently interact with our platform to meet your specific needs.

To streamline your development process, we have categorized the endpoints into logical groups and provided clear explanations of the parameters and data formats associated with each resource. Additionally, you'll find information on authentication methods, response formats, and any specific requirements for using particular endpoints.

Whether you're retrieving data, creating records, or performing complex operations, this Endpoint Resources Listing is your go-to reference for understanding and utilizing our API effectively. Feel free to explore the endpoints that align with your project's goals and requirements, and use this documentation as your trusted companion on your API integration journey.

Please refer to the table of contents or use the search functionality to quickly locate the endpoints and resources that interest you. If you have any questions, encounter issues, or need further assistance, our support team is here to help.

When reviewing the Post or Response Body it is recommended to click the 

option as shown below to display all nodes and properties.

Let's dive in and explore the wealth of possibilities our API offers. Happy coding!