API_AddRecord

Overview

Use API_AddRecord to add a record to a table. You invoke this call on a table dbid. When you use this call, you add fields and their values for the record. You must add values for all required fields or API_AddRecord returns an error.

The amount of data space consumed by a field depends on the field type. Read more in the online help.

top

Using field IDs and field names

When specifying fields, you can use either fids (field IDs) or field names. Field names are nearly identical to field labels; if you know the field label, you can determine the field name by converting all characters to lowercase and replacing all non-alphanumeric characters (including spaces) with an underscore.

For example, for a field with this label...

Event Name

...you should use this field name:

event_name

You can use a mixture of fids and field names in the same API call.

top

What happens if I write to built-in fields?

Every record has the same built-in QuickBase fields. For example, every record contains a Record ID. If you write to one of these fields by mistake, you’ll get an error and the record won’t be added. (You can bypass this error using the ignoreError parameter in your API call.)

top

What happens if I write to non-writable fields?

Fields such as formula fields, the iCalendar field, and the vCard field are non-writable; that is, you cannot add data to these fields. If your API call writes to a non-writable field, the call is ignored.

vCard and iCalendar are widgets linked to fields in a table. If you want to add data to these, you must write to those table fields; the vCard and iCalendar fields will be updated with that data.

top

Can I add a record without supplying data for all fields?

You must supply field data for all required fields. You are not required to supply values for fields that are not required, but if you do not, those fields will default to the values specified in field properties.

top

What data validation is enforced on field data I write?

QuickBase validates data in some, but not all, cases. For example, in a field of type Email, you can supply a non-valid email address and QuickBase will add it. However, in other cases, QuickBase will not write invalid data to the record. For example, if you supply an invalid value for Numeric or Phone Number field,  QuickBase won't write the data to the field; however, unless these fields are required, QuickBase will add the record.

top

Request parameters

The following parameters are available:

Parameter Value Required?

field

Specify values for the fields that make up the record you want to add using either the fid attribute or name attribute of the <field> element.

For example:

<field fid=”18”>Hi!</field>
<field name=”Message”>Hi!</field>

You must specify all required fields.

The values you enter here will vary, depending on field type. See How to specify values for different field types for more information.

yes

disprec

Set this parameter to 1 to specify that the new record should be displayed within the QuickBase application. An application login required before the record can be displayed. If you use this parameter, QuickBase, returns the normal QuickBase HTML page that displays the record.

Omit this property if you don't want the new record to display within the QuickBase application.

no

fform

Set this parameter to 1 if you are invoking API_AddRecord from within an HTML form that has checkboxes and want those checkboxes to set QuickBase checkbox fields.

Omit this property if you don't need QuickBase to set checkbox fields based on your HTML page.

no

ignoreError

Set this parameter to 1 to specify that no error should be returned when a built-in field (for example, Record ID#) is written-to in an API_AddRecord call.

If you do not set this parameter, QuickBase returns an error when API_AddRecord writes to a built-in field.

no

ticket

Specifies valid authentication ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses. See API Overview for more information on the authentication ticket.

yes

apptoken

Specifies a valid application token. See API Overview for more information on application tokens.

yes, if the application requires application tokens

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response.

no

msInUTC

Allows you to specify that QuickBase should interpret all date/time stamps passed in as milliseconds using Coordinated Universal Time (UTC) rather than using the local application time.

Set this parameter to 1 if you want to use Coordinated Universal Time. See usage example.

no

top

How to specify values for different field types

The following table describes how you can specify values for different field types. Note that, once you enter values using API_AddRecord, you can set properties for each field using API_SetFieldProperties.

Field Type Acceptable values

Text

Any characters, special characters, numbers, or symbols.

Text -
Multi-line

Any characters, special characters, numbers, or symbols.

Text -Multiple Choice

A valid choice that has been set up for the multiple choice field. Note that QuickBase does not validate case here; if you enter "ford" and, in your application, the choice is "Ford," the choice will be accepted.

If you enter an invalid choice, QuickBase generates an error.

Numeric

Positive or negative numbers. QuickBase ignores any non-numeric characters you enter here, but will not generate an error.

If you've specified decimal places using API_SetFieldProperties, the value will be truncated  or lengthened accordingly.

Numeric -Currency

Positive and negative numbers, with or without decimals. The decimal character should match the decimal character set in the field's properties.

Numeric -Percent

A number that represents the percentage. Note that, if you want to indicate 80%, you should enter 80 in this field.

Numeric -Rating

A numeric rating, from 1 - 5. QuickBase displays ratings as stars; if you enter 3 in a Numeric-Rating field, QuickBase displays 3 out of 5 stars selected.

Date

A date in the format specified in the app's properties.

Alternatively, a date in milliseconds since January 1, 1970 00:00:00 UTC.  Note that the QuickBase HTTP API returns dates in this format, which is the same internal representation used by JavaScript.

Date/Time

A date and time. Dates should be in the format specified in the app's properties.

This field is an extended date field that can also contain the time, in the format HH:MM AM/PM. If you don't specify AM or PM, QuickBase defaults to AM. If you don't specify a time, QuickBase defaults to 12:00 AM.

Time of Day

A time in this format: HH:MM AM/PM.

If you do not specify AM or PM, QuickBase defaults to AM.

Duration

A number that indicates a period of time. Note that you must use API_SetFieldProperties to set the unit of measure.

If you enter a non-numeric value here, QuickBase ignores the value (no error is generated.)

Checkbox

A string that indicates whether the checkbox is checked or not.

To specify that a checkbox is checked, enter any of these values:

  • 1

  • yes

  • true

  • on

To specify that a checkbox is not checked, enter any string other than those listed above, or leave the parameter blank. If a checkbox field is required, and does not default to "checked," you must enter some value to be able to save the record.

Phone Number

A phone number, with or without an extension. Enter a 10-digit string of numbers. You are not required to enter special characters (parentheses or dashes).

Example: For this phone number:

(123) 456-7890

...enter

 1234567890

If you want to include an extension, you can enter x after the last digit of the phone number, followed by the numeric characters that make up the extension. There is no minimum or maximum character limit on extensions.

Example: For this phone number:(123) 456-7890 x9876

...enter

 1234567890x9876

QuickBase ignores any non-numeric character you enter here (except for the x used for extensions).

Email Address

An email address (joeuser@example.com).

Note that if you enter an invalid email address, QuickBase does not generate an error.

User

A QuickBase user's email address or QuickBase user name.

 

List - User

QuickBase users' email addresses, QuickBase user names, or hashed user IDs, separated by semi-colons.

Example: joe@example.com;sue@example.com

File Attachment

A base64-encoded file. See Managing Files for more information about uploading files.

Note that you must not use MIME encoding and must not include MIME headers. Note that many base64 encoders or base64 encoding methods are for MIME type encoding and will not work with QuickBase.

You must not insert any newline characters when you base64 encode the file. If your file attachments appear to upload but don’t display in QuickBase, double check for presence of the new line.  

In the opening <field> tag, insert the filename attribute in addition to the fid or name attribute, as shown in this example:

<field fid=”22” filename=”profilePhoto.jpg”>

The filename attribute value should be set to the name of the file with no path specified. Insert the base64-encoded text from the encoded file between the opening and closing <field> tags.

URL

A web address. If you don't enter "http://", QuickBase adds it for you.

Note that if you enter an invalid web address, QuickBase does not generate an error.

Report Link

Report links are derived from other fields. You can update which report is linked to by updating the field that the report link refers to. You can't write to this type of field directly. If your API writes to a Report Link field, QuickBase ignores the call.

iCalendar

iCalendar fields are derived from other fields. You can update this type of field only by updating the fields to which it refers. You can't write to this type of field directly. If your API writes to an iCalendar field, QuickBase returns an error.

vCard

vCard fields are derived from other fields. You can update this type of field only by updating the fields to which it refers.  You can't write to this type of field directly If your API writes to a vCard field, QuickBase returns an error.

Predecessor

The record id of the predecessor record. Note that if you enter an invalid record ID here, QuickBase returns an error.

Formula fields

Formula fields are derived from other fields. You cannot write to this type of field directly. If your API writes to a formula field, QuickBase returns an error.

top

Response values

The response to this call contains the following:

Element Name Value

action

The originating request, for example, API_AddRecord.

errcode

Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.)

0 indicates that no error was encountered.

errtext

Text that explains the error code.

"No error" indicates that no error was encountered.

udata

Optional. Contains any udata value supplied in the request.

rid

Record ID of the record that was added

update_id

Used to detect update conflicts when invoking API_EditRecord.

You could save this update ID when you add a new record, but it would be better to instead get the most recent update_id value later when you query for the record to get it and update it.

top

Sample XML Request

Example Using Field Names

<qdbapi>
   <udata>mydata</udata>
   <ticket>2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25</ticket>
   <apptoken>dtmd897bfsw85bb6bneceb6wnze3</apptoken>
   <field name="event_name">party at Lindisfarne</field>
   <field name="description">dress in style of the epoch</field>
   <field name="location">lindisfarne island</field>
   <field name="start_time">06-08-0793</field>
   <field name="end_time">10-14-1066</field>
</qdbapi>

Example Using Field IDs

<qdbapi>
<udata>mydata</udata>
<ticket>2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25</ticket>
<apptoken>dtmd897bfsw85bb6bneceb6wnze3</apptoken>
<field fid=”8”>party at Lindisfarne</field>
<field fid="9">dress in style of the epoch</field>
<field fid="10">lindisfarne island</field>
<field fid="11">06-08-0793</field>
<field fid="12">10-14-1066</field>
</qdbapi>

Example with a truncated base64-encoded file attachment

The following request contains a truncated file in base64 encoding. Because the file is truncated, this sample won't work as shown. Replace it with your own encoded file.

POST https://quickbase.com/db/6mpjiez8?
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION:API_AddRecord

<qdbapi>
<ticket>2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25</ticket>
<apptoken>dtmd897bfsw85bb6bneceb6wnze3</apptoken>
<udata>mydata</udata>
<field name="email">cucamonga@chuck.com</field>
<field name="assigned_number">291</field>
<field name="text">OK Corral</field>
<field name="telephone">650-345-8768.3456</field>
<field fid="22" filename="Model_T.jpg">
8D6AAAOEJJTQQIAAAAAAAQAAAAAQAAAkAAAAJAAAAAADhCSU0EBgAAAAAABwAEAAAAAQEA
4AJ0ZpbGUgd3JpdHRlbiBieSBBZG9iZSBQaG90b3Nob3CoIDQuMAD/7gAOQWRvYmUAZAAAAAAB
9sAhAAGBAQEBQQGBQUGCQYFBgkLCAYGCAsMCgoLCgoMEAwMDAwMDBAMDAwMDAwMDAwMDAwMDAwM
DAwMDAwMDAwMDAwMAQcHBw0MDRgQEBgUDg4OFBQODg4OFBEMDAwMDBERDAwMDAwMEQwMDAwMDAw
MDAwMDAwMDAwMDAwMDAwMDAwMDAz/wAARCAEsAWQDAREAAhEBAxEB/90ABAAt/
8QBogAAAAcBAQEBAQAAAAAAAAAABAUDAgYBAAcICQoLAQACAgMBAQEBAQAAAAAAAAABAAIDBAUG
BwgJCgsQAAIBAwMCBAIGBwMEAgYCcwECAxEEAAUhEjFBUQYTYSJxgRQykaEHFbFCI8FS0eEzFmL
wJHKC8SVDNFOSorJjc8I1RCeTo7M2F1RkdMPS4ggmgwkKGBmElEVGpLRW01UoGvLj88TU5PRldY
WVpbXF1eX1ZnaGlqa2xtbm9jdHV2d3h5ent8fX5/
c4SFhoeIiYqLjI2Oj4KTlJWWl5iZmpucnZ6fkqOkpaanqKmqq6ytrq+hEAAgIBAgMFBQQFBgQIA
wNtAQACEQMEIRIxQQVRE2EiBnGBkTKhsfAUwdHhI0IVUmJy8TMkNEOCFpJTJaJjssIHc9I14kSD
F1STCAkKGBkmNkUaJ2R0VTfyo7PDKCnT4/
OElKS0xNTk9GV1hZWltcXV5fVGVmZ2hpamtsbW5vZHV2d3h5ent8fX5/
c4SFhoeIiYqLjI2Oj4OUlZaXmJmam5ydnp+So6SlpqeoqaqrrK2ur6/
9oADAMBAAIRAxEAPwCK6Bd3Ea3CaXJDbxS2wLSSVZGVNvTmj+NTGSGIdVk+1yzFxkg0WmpdEHpc
k9vO2n21xBP+huF1ajklHWcEyxFmQer6a+or8x8CumWSx0b7mVSTO2S3mRoNOkMWnXUTGPkP3QV
2EkXpcOfAMF/Y/axsmVDqxromtzb2/
r2b+qpjjAgmSTkSY0XkpJ2J+Mslar8OZHhjkvAsv3sLp4UmuYxMPVS0ujGpkjNAKcWIDpKvwy/
Bz4rz+3+8wyxBmAk1xJDJr2l2c6xy2mlwT31xAw5Rx8jxjJ/
jXJbKLRGnfbm6foz1Dy6cPV9RvV+38Xp8vtV/3bz4YQjdZ8X1j9r67/svXp6n/UP6X/
PH1P8AizAl/9kA
</field>

top

URL alternative

https://<target_domain>/db/57pa5vjf?act=API_AddRecord&_fnm_second_year=1776
&_fid_8=changed&ticket=<your_ticket>&apptoken=dtmd897bfsw85bb6bneceb6wnze3

where <target_domain> is the domain against which you are invoking this call, for example, intuit.quickbase.com.

top

Sample response

<?xml version="1.0" ?>
<qdbapi>
   <action>API_AddRecord</action>
   <errcode>0</errcode>
   <errtext>No error</errtext>
   <udata>mydata</udata>
   <rid>21</rid>
   <update_id>1206177014451</update_id>
</qdbapi>

top   

© 1999-2014 Intuit Inc. All rights reserved. Legal Notices.