Knowledge Base

API AddRecord | ADVANCED

The API_AddRecord call is one of the most basic API calls in Quick Base – and empowers a user to create a single record based on pre-defined conditions.

Common use cases for using the API_AddRecord might include:

✓ Creating a custom button in Quick Base that creates a new record with one click

✓ Implement in Quick Base Webhooks to add a record once certain changes occur

✓ Custom Scripting (either client or server side)

Let’s picture a scenario where you have a system where users ‘vote’ on a particular item or issue. In this example – you want them to click a button to ‘vote’, and by doing so, a record is added that logs their user and a ‘yes’ response on whatever topic is being discussed. An easy solution would be putting an API_AddRecord into a button to save several steps.

EDITORS NOTE: This document will only cover the URL Alternative for utilizing API_AddRecord. The URL alternative is applicable for use in native Quick Base buttons, Webhooks, as well as GET requests in custom scripting. This article does not cover POST Requests, although the details are transferrable.

Please reference the Quick Base API documentation for API_AddRecord for any additional information that is not included below

Let’s start with the example provided in the Quick Base API Documentation

https://target_domain/db/target_dbid?a=API_AddRecord&_fnm_second_year=1776&_fid_8=changed&ticket=auth_ticket&apptoken=app_token

Part 1 – the Target

The target is the Quick Base table you want to add a record in. The colored text below represents the target.

https://target_domain/db/target_dbid?a=API_AddRecord&_fnm_second_year=1776&_fid_8=changed&ticket=auth_ticket&apptoken=app_token

The target_domain is your Quick Base realm. In my case, my Quick Base realm is quandarycg.quickbase.com. So, the first part of my URL would look like –

https://quandarycg.com/db/

The target_dbid is the table you want to add a record in. Every table in Quick Base is uniquely identified by a table id. To find your unique table id, navigate your browser to the table where you are trying to add a record. Once there, take a look at your browsers URL – the text you are looking for is the string of characters that immediately follow after the “/db/”, and stops before the “?a”. In the case of the Quandary CG Knowledge Base, we have a table for ‘External Records’ to hold test data from Knowledge Base users. That table is found via the following link for us:

https://quandarycg.quickbase.com/db/bn6wwekqv?a=td

The Target DBID then, is bn6wwekqv.

Once you have your Quick Base realm and your target DBID, you bring it all together to build your Target for this API call. From the above examples –

https://quandarycg.quickbase.com/db/bn6wwekqv

Part 2 – the API Call

The API call is how you tell Quick Base what you are trying to do. It is the core piece that determines how Quick Base interprets everything else and what it needs from you. Everything in the API call should start with “?a=API_”. Since this document is about adding records, your full API call should read as “?a=API_AddRecord”. Make sure you do not forget the “API_” piece. The updated URL will be as follows:

https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord

Part 3 – Using App Tokens

Depending on your app – Application Tokens may or may not be required. For more info on how to use app tokens, please reference the Application Tokens article. If they are required, then your URL needs to call out that essential piece. Doing so requires that you add “&apptoken=” as the next part of your URL.The updated URL would be as follows:

https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord&apptoken=itgoeshere

Part 4 – Authentication/Ticket

A requirement of an API call is that the user or process making the call be logged in or authenticated in some form. For simplicity – I recommend using User Tokens. For an explanation of user tokens, please reference the User Tokens article. Incorporating a user token is similar to using apptokens, whereby you add an additional URL param to your API call for Quick Base to read. That string is “&usertoken=”. The updated URL will be as follows:

https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord&apptoken=itgoeshere&usertoken=usertokengoeshere

Part 5 – Setting Field Values

Setting field values means when your new record is created, you can set certain field values to automatically fill and and save. From the example at the beginning with voting on a topic, we want to pre-define fields to capture who the user is and what their answer is on a certain topic.

BEST PRACTICE: It is strongly recommended that you use field ID’s in all API calls. While the Quick Base API documentation / examples will show that you can use Field Names in lieu of Field ID’s, it is advised you do not use them given that they can change over time, while the Field IDs are immutable.

Setting different field values is just a matter of rinse and repeat using fid#=. Make sure the field ID of the various inputs you want to set in the target table. Before you actually set up your API call, you should identify the various inputs you want to set and their associated Field IDs. With those identified, you will append fid#=value to your URL string for each field you want a value set for. For example,

_fid_6=value1&_fid_7=value2&_fid_8=value3

Notice each new field value is separated by &, but the general format is the same. That string should be appended to what you have set up from Parts 1-4. To set up our button to vote on a topic described in the very beginning- it would look something like this:

https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord&apptoken=itgoeshere&usertoken=usertokengoeshere&_fid_6=_curuser_&_fid_7=I’m voting Yes&_fid_8=The Topic I’m voting on is this Article being awesome

Part 6 – Test it

To see a simple example in action – click the link below:

[https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord&_fid_6=I created a new record through the API&_fid_10=today](https://quandarycg.quickbase.com/db/bn6wwekqv?a=API_AddRecord&_fid_6=I created a new record through the API&_fid_10=today)

You should see a result like this:

You can also try it out in the Quandary Knowledge Base to see it live in Quick Base

To take the next step – take a look at the article on API_EditRecord to modify existing records

EDITORS NOTE: In March 2019, Quick Base released a clist Parameter that can now be included in all AddRecord and EditRecord calls. By including this in your API call – you can define a list of field ids such as “&clist=1.2.3.4.5” such that the XML response returns the value of these fields in the record


Copyright ©2020 - Quandary Consulting Group