API_ImportFromCSV

Overview

Use API_ImportFromCSV to add or update several records. You invoke this call on a table-level dbid. You can add AND update in the same API_ImportFromCSV request. (For an Add, leave the Record ID empty.)

The clist parameter is optional when adding new records to a table. When updating existing records, the clist parameter must contain the field ID for the key field (usually 3 for the Record ID#). The CSV file you're importing must also include a column that contains the value of the key field for each record that will be updated.

top

Request parameters

Parameter Value Required?

records_csv

An aggregate containing the actual records you are importing.

<records_csv>
   <![CDATA[
      your, record, values, go, here
      and, hopefully, here, as, well
   ]]>
</records_csv>

For field format, usage, and any validation for fields of particular types, see API_AddRecord.

yes

clist

A period-delimited list of field IDs that indicates how the columns in the CSV file will map to fields in the table when the import happens. To prevent a column in the CSV file from being imported, enter a 0 in the field ID list.

This means that the first field ID in the list maps to the first column in the CSV file, the second field ID maps to the second column in the CSV file, and so forth.

In the following example, the CSV file contains 4 columns. Quick Base will not import either the first or the third columns. The second column will map to field ID 7, and the fourth column will map to field ID 6.

<clist>0.7.0.6</clist>

Yes, if you are updating records, or you want the columns in the CSV file to map to certain fields in the table.

clist_output

Specifies which fields should be returned in addition to the record ID and updated ID. Specify a period-delimited clist string, for example:

<clist_output>0.7.0.6</clist_output>

no

decimalPercent

Set this parameter to 1 so that decimal values like 0.50 will be interpreted to mean 50%.

no

skipfirst

Set this parameter to 1 to prevent Quick Base from importing the first row of data in a CSV file. You must specify this parameter if the first row of your CSV file contains column names.

Omit this property if you don't want to prevent the first row to be imported.

no

ticket

A valid authentication ticket.

The authentication ticket is returned via the API_Authenticate call.

yes, one of:

  • ticket
  • username/password
  • user token

usertoken

The user token is an alternative means of authentication, used for API access. User tokens cannot be used to access the Quick Base UI.

yes, one of:

  • ticket
  • username/password
  • user token

apptoken

A valid application token.

yes, if the application requires application tokens

udata

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

no

msInUTC

Allows you to specify that Quick Base 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

mergeFieldId

With this parameter, the import uses the field specified as the key, instead of the key field for the table.

  • The specified merge field must contain unique values.

  • Values for the table key and/or record ID field will be ignored from input to prevent data corruption.

  • If the specified merge field uses a formula, and a record cannot be found by its value, a new record will be added if the resulting formula value is a valid value for the field.

  • Record ID or other table key field can be used as the specified merge field.

  • The clist parameter is required if this parameter is used.

To specify the field, use the field ID, for example:

<mergeFieldId>10</mergeFieldId>

For more details, read an article about the parameter on the Quick Base Community site.

no

top

Response values

Element Name Value

action

The originating request, for example, API_ImportFromCSV.

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.

num_recs_added

The number of records added to the table

num_recs_input

The total number of records in the CSV file

num_recs_updated

The number of records in the table that were updated

rids

A list of the record IDs for all the records that were either added or updated

update_id

Attribute of each rid element that defines the update_id for the record.

Update IDs are used to detect update conflicts in subsequent operations with API_EditRecord.

top

Sample XML Request

POST https://target_domain/db/target_dbid HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_ImportFromCSV

<qdbapi>
   <udata>mydata</udata>
   <ticket>auth_ticket</ticket>
   <apptoken>app_token</apptoken>
   <records_csv>
      <![CDATA[
         First Name,Last Name,Company,Phone,Cell Phone,Zip
         Bruce,Anderson,Reyes Inc,(474) 555-0514,(390) 555-8927,<-80145>
         Judy,Atwell,Conner Supplies,(499) 555-1072,(763) 555-1325,<-50737>
         Kris,Babs,Willis Orchards,(428) 555-6791,(481) 555-1335,<-81504>
      ]]>
   </records_csv>
   <clist>7.8.6.5.4</clist>
   <skipfirst>1</skipfirst>
</qdbapi>

where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.

top

Sample XML Request to Add New Records

<qdbapi>
<records_csv>
<![CDATA[First Name,Last Name,Company,Phone,Cell Phone,Zip
Bruce,Anderson,Reyes Properties,(474) 555-0514,(390) 555-8927,<-80145>
Judy,Atwell,Conner Garden Supplies,(499) 555-1072,(763) 555-1325,<-50737>
Kristie,Babcock,Willis Orchards,(428) 555-6791,(481) 555-1335,<-81504>
Linda,Bailey,Willis Orchards,(544) 555-8912,(491) 555-1449,<-07738>
Mike,Balak,Nye Properties,(253) 555-9766,(637) 555-4566,<-93341>
Renee,Barley,Lew Plumbing,(486) 555-4747,(268) 555-5904,<-98841>
Howard,Bayne,Holly Heating and Electric,(743) 555-2294,(756) 555-7934,<-40984>
David Y.,Becker,Express Service,(825) 555-8433,(255) 555-2867,<-49873>
]]></records_csv>
<clist>7.8.6</clist>
<skipfirst>1</skipfirst>
   <ticket>auth_ticket</ticket>
   <apptoken>app_token</apptoken>
</qdbapi>

top

Sample XML Response (Add New Records)

<?xml version="1.0" ?>
<qdbapi>
 <action>API_ImportFromCSV</action>
 <errcode>0</errcode>
 <errtext>No error</errtext>
 <num_recs_input>8</num_recs_input>
 <num_recs_added>8</num_recs_added>
<rids>
 <rid update_id="1057961999003">1</rid>
 <rid update_id="1057961999003">2</rid>
 <rid update_id="1057961999003">3</rid>
 <rid update_id="1057961999003">4</rid>
 <rid update_id="1057961999003">5</rid>
 <rid update_id="1057961999003">6</rid>
 <rid update_id="1057961999003">7</rid>
 <rid update_id="1057961999003">8</rid>
</rids>
</qdbapi>

top

Sample Response (Update Existing Records)

<qdbapi>
<action>API_ImportFromCSV</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<num_recs_input>2</num_recs_input>
<num_recs_updated>2</num_recs_updated>
<rids>
<rid>7</rid>
<rid>8</rid>
</rids>
</qdbapi>

 

Go back    |     |  

© 1999-2018 QuickBase, Inc. All rights reserved. Legal Notices.