QuickBase HTML API Guide (Draft) by mactucket

QuickBase SDK ®

HTML API Programmer’s Guide

Version 1.0

QuickBase SDK version 1.0, released April 2008. (c) 2008 Intuit Inc. All rights reserved. QuickBase and Intuit are registered trademarks of Intuit Inc. All other trademarks are the property of their respective owners and should be treated as such. Acknowledgement: This product includes software developed by the Apache Software Foundation (<http://www.apache.org>) (c) 1999-2006 The Apache Software Foundation. All rights reserved. Intuit Inc. P.O. Box 7850 Mountain View, CA 94039-7850 For more information about the QuickBase SDK and the SDK documentation, visit http://developer.intuit.com/QuickBaseSDK/.

Chapter 1: Programming with the HTML API What is the HTML API? . . . . . . . . . . . . . . . . . . . QuickBase SDK Support of the HTML API. . . . . . . What Can I Do with the API? . . . . . . . . . . . . . . . Communication With a QuickBase Application . . . User Setup . . . . . . . . . . . . . . . . . . . . . . . . . Communication via API Calls. . . . . . . . . . . . . How to Use Tickets: Tickets vs. Username and

....... ....... ....... ....... ....... ....... Password

. . . . . . .

11 11 11 14 14 14 15

Chapter 2: User Access and Your Application Secure Communications: Ticket and DevKey . How Managing Users Register the Devkey How Developers Obtain a DevKey . . . . . . How Compromised Security Situations are API Calls with No DevKey . . . . . . . . . . . . Access to QuickBase (Login) . . . . . . . . . . . . The Typical User Management Cycle . . . . . . . API Calls for Basic User Management . . . . Moving Users in and out of Roles. . . . . . .

....... ....... ....... Handled . ....... ....... ....... ....... .......

. . . . . . . . .

17 17 17 18 18 19 19 19 20

How QuickBase Views and Reports Relate to Queries . . Is There a Default View or Must I Construct a View? How Do I Construct a View? . . . . . . . . . . . . . . . . . What is a Report and How is it Related to a View? . . How is an API Query Related to Reports and Views? Video: Constructing Reports, Views, Queries. . . . . . The Components of a Query . . . . . . . . . . . . . . . . . . . How to Supply the Query Parameter . . . . . . . . . . . Constructing the Query String 24 Referencing a Saved Query 25 Column List (clist) Parameter . . . . . . . . . . . . . . . . Sort List (slist) Parameter. . . . . . . . . . . . . . . . . . . Options Parameter. . . . . . . . . . . . . . . . . . . . . . . . Format Parameter: Structured vs. Unstructured . . . Sample Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . .

21 22 22 22 23 23 23 23

. . . . .

26 26 27 27 28

Chapter 3: Building and Using Queries

Chapter 4: Uploading and Downloading Files Uploading Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Downloading Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

How to Understand the XML Samples . . . . . . . . . . . . . . . . . . Some Optional API Input Parameters . . . . . . . . . . . . . . . . . . API_AddField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 38 Example Response 38 API_AddRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 39 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fids vs. Field Names 40 What Happens If I Write to Built-In Fields? 40 What Happens if I Write to Non-Writable Fields? 40 How Do I Get Data Into a vCard or iCalendar? 40 Adding a Record Without Supplying Data for All Fields 40 How Do I Upload a File When I Add My Record? 40 What Data Validation Is Enforced on Field Data I Write? 41 Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 44 Example Response 45 API_AddReplaceDBPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 47 Example Response 48 API_AddUserToRole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 50 Example Response 51 API_Authenticate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 52 URL Alternative 52 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 53 Sample XML Response 54 API_ChangeRecordOwner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 55 URL Alternative 55 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . .

33 34 36 36 37 37

. . . . . . . . . . . . . . 39 . . . . . . . . . . . . . . 39

. . . . . . . . . . . . . . 42 . . . . . . . . . . . . . . 44

. . . .

46 46 47 47

. . . .

49 49 50 50

. . . . . . . . . . . . . . 52

. . . . . . . . . . . . . . 52 . . . . . . . . . . . . . . 53 . . . . . . . . . . . . . . 53

. . . . . . . . . . . . . . 55

. . . . . . . . . . . . . . 55 . . . . . . . . . . . . . . 55 . . . . . . . . . . . . . . 56

Sample XML Request 56 Sample XML Response 56 API_ChangeUserRole . . . . . . . . Header and XML 57 URL Alternative 57 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . . Sample XML Request 58 Sample XML Response 58 API_CloneDatabase . . . . . . . . . Header and XML 59 URL Alternative 59 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . . Sample XML Request 60 Sample XML Response 60 API_CreateDatabase . . . . . . . . . Header and XML 61 URL Alternative 61 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . . Sample XML Request 62 Sample XML Response 62 API_CreateTable . . . . . . . . . . . . Header and XML 64 URL Alternative 64 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . . Sample XML Request 65 Sample XML Response 65 API_DeleteDatabase . . . . . . . . . Header and XML 66 URL Alternative 66 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . . Sample XML Request 67 Sample XML Response 67 API_DeleteField . . . . . . . . . . . . Header and XML 68 URL Alternative 68 Usage . . . . . . . . . . . . . . . . Request Parameters. . . . . . . Response Values . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Sample XML Request 69 Sample XML Response 69 API_DeleteRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 70 URL Alternative 70 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 71 Sample XML Response 71 API_DoQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 72 URL Alternative 72 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For More Information on QuickBase Queries... 72 About API_DoQuery Parameters 72 Query Operators 73 Request Parameters . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 76 Sample XML Response (structured format) 76 API_EditRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 80 URL Alternative 80 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 83 Example Response 83 API_FieldAddChoices . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 84 URL Alternative 84 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 85 Sample XML Response 85 API_FieldRemoveChoices . . . . . . . . . . . . . . . . . . . . . . Header and XML 87 URL Alternative 87 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 88 Sample XML Response 88 API_FindDBByName. . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 89 URL Alternative 89

. . . . . . . . . . . . . . . . . . . . . 70

. . . . . . . . . . . . . . . . . . . . . 70 . . . . . . . . . . . . . . . . . . . . . 70 . . . . . . . . . . . . . . . . . . . . . 71

. . . . . . . . . . . . . . . . . . . . . 72

. . . . . . . . . . . . . . . . . . . . . 74 . . . . . . . . . . . . . . . . . . . . . 75

. . . . . . . . . . . . . . . . . . . . . 80

. . . . . . . . . . . . . . . . . . . . . 80 . . . . . . . . . . . . . . . . . . . . . 80 . . . . . . . . . . . . . . . . . . . . . 82

. . . . . . . . . . . . . . . . . . . . . 84

. . . . . . . . . . . . . . . . . . . . . 84 . . . . . . . . . . . . . . . . . . . . . 84 . . . . . . . . . . . . . . . . . . . . . 85

. . . . . . . . . . . . . . . . . . . . . 87

. . . . . . . . . . . . . . . . . . . . . 87 . . . . . . . . . . . . . . . . . . . . . 87 . . . . . . . . . . . . . . . . . . . . . 88

. . . . . . . . . . . . . . . . . . . . . 89

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 90 Sample XML Response 90 API_GenAddRecordForm . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 91 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API_GenResultsTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 93 URL Alternative 93 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedding a QuickBase View into a Web Page 93 A Sample Web Page HTML with an Embedded Table 94 Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API_GetDBInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 97 URL Alternative 97 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 98 Sample XML Response 98 API_GetDBPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 99 URL Alternative 99 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . API_GetDBvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 101 URL Alternative 101 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 102 Sample XML Response 102 API_GetNumRecords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 103 URL Alternative 103 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 104 Sample XML Response 104

. . . . . . . . . . . . . . . . 89 . . . . . . . . . . . . . . . . 89 . . . . . . . . . . . . . . . . 90

. . . . . . . . . . . . . . . . 91 . . . .

. . . .

91 91 91 93

. . . . . . . . . . . . . . . . 93

. . . . . . . . . . . . . . . . 95 . . . . . . . . . . . . . . . . 96 . . . . . . . . . . . . . . . . 97

. . . . . . . . . . . . . . . . 97 . . . . . . . . . . . . . . . . 97 . . . . . . . . . . . . . . . . 97

. . . . . . . . . . . . . . . . 99

. . . .

. 99 . 99 . 99 .101

. . . . . . . . . . . . . . . .101 . . . . . . . . . . . . . . . .101 . . . . . . . . . . . . . . . .102

. . . . . . . . . . . . . . . .103

. . . . . . . . . . . . . . . .103 . . . . . . . . . . . . . . . .103 . . . . . . . . . . . . . . . .103

API_GetOneTimeTicket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 105 URL Alternative 105 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 106 Sample XML Response 106 API_GetRecordAsHTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 107 URL Alternative 107 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedding a QuickBase View into a Web Page 107 Example Web Page Code 108 Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 109 Sample XML Response 110 API_GetRecordInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 111 URL Alternative 111 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 112 Sample XML Response 112 API_GetRoleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 114 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 115 Sample XML Response 115 API_GetSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 117 URL Alternative 117 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Table-Schema Coolness: Saved Queries For You to Use 117 More Table-Schema Coolness: Field Help as Tooltips 118 Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 118 Sample Application-level Response 119 Sample Table-level Response 119 API_GetUserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 121 URL Alternative 121 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . 105

. . . . . . . . . . . . . 105 . . . . . . . . . . . . . 105 . . . . . . . . . . . . . 105

. . . . . . . . . . . . . 107

. . . . . . . . . . . . . 109 . . . . . . . . . . . . . 109

. . . . . . . . . . . . . 111

. . . . . . . . . . . . . 111 . . . . . . . . . . . . . 111 . . . . . . . . . . . . . 112

. . . . . . . . . . . . . 114 . . . . . . . . . . . . . 114 . . . . . . . . . . . . . 114 . . . . . . . . . . . . . 115

. . . . . . . . . . . . . 117

. . . . . . . . . . . . . 118 . . . . . . . . . . . . . 118

. . . . . . . . . . . . . 121

Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 122 Sample XML Response 122 API_GetUserRole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 124 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 125 Sample XML Response 125 API_GrantedDBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 127 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 128 Sample XML Response 129 API_ImportFromCSV. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 130 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request to Add New Records 132 Sample XML Response (Added New Records) 133 Sample XML Request (Update Existing Records) 133 Sample XML Response (Update Existing Records) 133 API_ProvisionUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 134 URL Alternative 134 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 135 Sample XML Response 136 API_PurgeRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header and XML 137 URL Alternative 137 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample XML Request 138 Sample XML Response 138 API_RemoveUserFromRole. . . . . . . . . . . . . . . . . . . . . . . . . Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example XML Request 141

. . . . . . . . . . . . . . . . .122 . . . . . . . . . . . . . . . . .122

. . . . . . . . . . . . . . . . .124 . . . . . . . . . . . . . . . . .124 . . . . . . . . . . . . . . . . .124 . . . . . . . . . . . . . . . . .124

. . . . . . . . . . . . . . . . .127 . . . . . . . . . . . . . . . . .127 . . . . . . . . . . . . . . . . .127 . . . . . . . . . . . . . . . . .128

. . . . . . . . . . . . . . . . .130 . . . . . . . . . . . . . . . . .130 . . . . . . . . . . . . . . . . .131 . . . . . . . . . . . . . . . . .132

. . . . . . . . . . . . . . . . .134

. . . . . . . . . . . . . . . . .134 . . . . . . . . . . . . . . . . .135 . . . . . . . . . . . . . . . . .135

. . . . . . . . . . . . . . . . .137

. . . . . . . . . . . . . . . . .137 . . . . . . . . . . . . . . . . .138 . . . . . . . . . . . . . . . . .138

. . . .

.140 .140 .141 .141

Example Response 141 API_RenameApp . . . . . . . . . . . . . Header and XML 143 URL Alternative 143 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . Response Values . . . . . . . . . . Sample XML Request 144 Sample XML Response 144 API_SendInvitation . . . . . . . . . . . Header and XML 145 URL Alternative 145 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . Response Values . . . . . . . . . . Sample XML Request 146 Sample XML Response 146 API_SetDBvar . . . . . . . . . . . . . . . Header and XML 147 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . Response Values . . . . . . . . . . Sample XML Request 148 Sample XML Response 148 API_SetFieldProperties . . . . . . . . . Header and XML 149 URL Alternative 149 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . Response Values . . . . . . . . . . Sample XML Request 150 Sample XML Response 150 API_SignOut . . . . . . . . . . . . . . . . Header and XML 152 URL Alternative 152 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . . Response Values . . . . . . . . . . Sample XML Request 153 Sample XML Response 153 API_UploadFile . . . . . . . . . . . . . . URL 154 Usage . . . . . . . . . . . . . . . . . . Sample Response 154 API_UserRoles . . . . . . . . . . . . . . Header and XML 155 Usage . . . . . . . . . . . . . . . . . . Request Parameters . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Response Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 Sample XML Request 156 Sample XML Response 156

Appendix A: Error Codes

CHAPTER 1 PROGRAMMING WITH THE HTML API

1 1

The QuickBase SDK Kingussie framework for Flex is the preferred way to program applications using QuickBase. That framework provides wizards, tools, precoded widgets and forms, easy deployment over the web, and eliminates nearly all of the complexities in programming for QuickBase. It is by far the easiest and fastest way to get your application coded and to market. However, not all implementations can use Flex and the Kingussie framework. For those types of applications, we provide the HTML API.

What is the HTML API? The HTML API is a collection of calls for accessing QuickBase applications over the web. It is an interface only--there are no components, modules, libraries, and so forth that are installed at the application end. The API can be invoked in either of two ways. •

As an XML request string POSTed to QuickBase

•

As a URL sent in a GET request (e.g. sent from a browser, or embedded in a web page or Word document).

The QuickBase response is returned to your application in XML format. However, there are a couple of calls that return HTML. (The HTML returns are primarily for certain API calls that are embedded in a web page or Word document.)

QuickBase SDK Support of the HTML API To assist you in programming with the HTML API, the QuickBase SDK package includes this document, a tool called SendApiCalls that you can use to POST any API request, and some sample XML requests.

What Can I Do with the API? The API scope can be separated into the following general categories: •

Providing secure access to QuickBase and QuickBase applications.

•

Managing access through the QuickBase roles feature.

•

Automating the application life cycle: creation, deletion, and copying (cloning) of applications.

•

â&#x20AC;˘

Adding, updating, deleting, and querying table records

The following table groups the API calls under each of these categories.

Table 1-1

API calls by category

Functional Categories

Related API Calls and Features

Application and table metadata

API_FindDBByName API_GetDBInfo API_GetSchema API_GrantedDBs

Application life cycle

API_CloneDatabase API_CreateDatabase API_DeleteDatabase API_RenameApp

File upload and download

API_AddRecord API_EditRecord API_UploadFile

Misc

API_AddReplaceDBPage API_GetDBPage API_GetDBvar API_SetDBvar

Secure access to QuickBase applications

requires https communication requires ticket and developer key API_Authenticate API_GetOneTimeTicket API_SignOut

Table and field management

API_AddField API_CreateTable API_DeleteField API_FieldAddChoices API_FieldRemoveChoices API_SetFieldProperties

Table record management

API_AddRecord API_ChangeRecordOwner API_DeleteRecord API_DoQuery API_EditRecord API_GenAddRecordForm API_GenResultsTable API_GetNumRecords API_GetRecordAsHTML API_GetRecordInfo API_ImportFromCSV API_PurgeRecords

Functional Categories User access management

Related API Calls and Features API_AddUserToRole API_ChangeUserRole API_ChangeRecordOwner API_GetRoleInfo API_GetUserInfo API_GetUserRole API_ProvisionUser API_RemoveUserFromRole API_SendInvitation API_UserRoles

Communication With a QuickBase Application There are two facets of communication with QuickBase: •

The one time setup of the user required to enable communication

•

The actual communication through API calls

User Setup In order for someone to use a QuickBase application accessed through the API, they will need to be assigned a role within that QuickBase application by the application administrator. The roles are set up in QuickBase to provide varying kinds of access. The user will also need a QuickBase login. Typically a user is invited to register for a QuickBase login by an email invitation, which in the API is done through API_SendInvitation. (See also “API_ProvisionUser” .) Finally, the user will need the application developer’s devkey, as described in the topic “Secure Communications: Ticket and DevKey”.

Communication via API Calls Once the user is fully set up, API_Authenticate can be invoked using the user’s QuickBase login name and password. This call returns a ticket cookie and an XML representation of the ticket as well for inclusion in subsequent API calls The ticket should not be thought of as a session ticket. By default it is valid for 8 hours, but this default can be changed in the call to API_Authenticate to anywhere from an hour to just about forever. Once there is a valid ticket, API calls can be invoked to access QuickBase data. Each API call (except those noted under “API Calls with No DevKey”) must include the ticket and the devkey. 14 Chapter 1: Programming with the HTML API (c) 2008 Intuit Inc. All rights reserved.

Upon receiving the API call, QuickBase examines the ticket and devkey. If the ticket is valid and the devkey is a registered devkey matching the application, the API call is allowed to proceed.

How to Use Tickets: Tickets vs. Username and Password If a user is accessing a QuickBase application through a web browser, once the call to API_Authenticate has been made successfully, the ticket cookie will be used automatically: there is no need to explicitly supply the ticket value as returned in the XML. If your implementation isn’t through a web browser or you can’t use the cookie, you can supply the ticket value explicitly between the <ticket></ticket> tags as we show in our samples. What you should not do is hardcode the username and password parameter (and their values) in your request, even if it is over https.

Cl ick to Add or See Comments

CHAPTER 2 USER ACCESS AND YOUR APPLICATION

1 1

This chapter covers the QuickBase API and application-level features that govern access. The calls that provide these features can be grouped as follows: •

Secure communications: ticket and devkey

•

Access to QuickBase (login)

•

Managing user access to applications by moving users in and out of roles

•

Enabling easy application access for users through provisioning and invitation

•

Changing record ownership

You’ll notice one thing missing in this list: there are currently no calls to create or set up roles. You’ll need to do all that work in the QuickBase UI. The API calls only let you move users around in roles that are already created. There are default roles you could use (administrator, participant, viewer), but it’s likely that many applications will need their own role structure.

Secure Communications: Ticket and DevKey For greater security, all API calls except those called out under “API Calls with No DevKey” must contain both a ticket and a devkey. The ticket is returned from a successful call to API_Authenticate. The devkey is generated by QuickBase and given to the developer, who then gives the key to the end user (the application manager user). The managing user must use the QuickBase UI to enter the devkey into the QuickBase.

How Managing Users Register the Devkey The user registers the key by selecting from the main application menu Customize>Application->Developer Keys, which is a tabbed page. The user adds or deactivates developer keys in this form.

How Developers Obtain a DevKey A developer can request from 1 to 100 devkeys. The idea is that developers obtain one devkey and use it for all their cloned applications. In other words, there is not a separate devkey for each cloned instance (i.e., each purchaser) To obtain a devkey, you use the devkey form accessible from the User Profile Page and on the Application Site Map. The request developer key form looks like this:

Figure 2-1

The Request Developer Key form

How Compromised Security Situations are Handled If some user uses someone else’s devkey, and there is a complaint about this being unauthorized, the offending user will have access rights removed and the devkey will be revoked.

API Calls with No DevKey The following calls use a ticket only, not a ticket and a devkey: •

API_Authenticate

•

API_CreateDatabase

•

API_FindDBByName

•

API_GrantedDBs

•

API_SignOut

Cl ick to Add or See Comments

Access to QuickBase (Login) Login to QuickBase is provided through the API_Authenticate call, which returns a ticket and a ticket cookie. Just like a regular QuickBase login through the UI, the ticket by itself does not convey access to any applications. The application owner needs to assign an access role to the user first. There is also the call API_GetOneTimeTicket, which returns a one-use only ticket that expires after 5 minutes. The intended use for this is to support the API_UploadFile call, which is used by p Both the ticket and a valid devkey for the application need to be included for all API calls except the ones listed above.

Cl ick to Add or See Comments The Typical User Management Cycle After creating your application, tables and fields, and before inviting users to your application, you need to figure out what your system of roles should look like: what tables or fields should be accessed by which role, and what degree of access. All of this is done in the QuickBase UI and the QuickBase online help can lead you through the process. After you finish setting up roles in the UI, you can add users to the roles and then invite them to your application using API calls. Here is the typical user management cycle 1. I want to give you access to my application, so I first assign you an access role. 2. I invite you to my application via an email. 3. At some point, I may wish to change your role (e.g., a support rep could move to a sales rep role), or I may want to suspend or remove you from access roles altogether.

API Calls for Basic User Management If the user is an existing QuickBase user: 1. Use API_GetRoleInfo, if needed, to get the available roles. 1. If you know the user email, you can invoke API_GetUserInfo and get back the user’s user ID. 2. Use the user ID to invoke API_AddUserToRole call to give the user the access rights (role) you want to give. 3. Call API_SendInvitation to send an email inviting the user to the application. Access to QuickBase (Login) 19 (c) 2008 Intuit Inc. All rights reserved.

If the user is not a QuickBase user, 1. Use API_GetRoleInfo, if needed, to get the available roles. 2. Invoke API_ProvisionUser, supplying the role, user’s email, user fname (first name), and user’s lname (last name). The user is added to the specified role and a new user registration in QuickBase using the user values. (The user will have to complete the registration. 3. Call API_SendInvitation to send an email inviting the user to the application.

Moving Users in and out of Roles You can use API_UserRoles to get all the users that are in roles for your application, along with all of the roles for each user. You can use API_ChangeUserRole to move a user to a different role. You would also use this call if you wanted to suspend the user access, but still keep the user on the application access list to make it easier to activate their access again. This would be role 0, (zero), which is the “None” role, meaning no access. Later, you could invoke API_ChangeUserRole again to assign the user to an access role. You could call API_RemoveUserFromRole if you wanted to permanently remove the user from access.

Cl ick to Add or See Comments

CHAPTER 3 BUILDING AND USING QUERIES

1 1

All of the HTML API calls are centered around the QuickBase application. Nearly all of the API calls are centered on creating the application and its tables, governing access to it, and adding or updating data. Only two calls perform the critical function of returning the data you need in the display order (view) that you want. These two calls are “API_DoQuery” and “API_GenResultsTable”: both of which are covered in the language reference section. Both API_DoQuery and API_GenResultsTable make use of the same query mechanism to return data. They differ mainly in the overall format of the return: •

API_DoQuery returns XML that you can parse and process as you wish.

•

API_GenResultsTable can be embedded in a web page to automatically show the filtered records in the page as an HTML table when the page is opened in a browser.

This topic covers the query mechanism that both of these calls use.

How QuickBase Views and Reports Relate to Queries In the QuickBase UI, retrieved records are displayed in rows in a table, with the field data layed out in separate columns (Figure 3-1). This layout of record data is called a ‘view.”

Figure 3-1

A QuickBase View

Why do we call it a view, and not just “record data”? Because a view seldom contains all or even most of the data fields in a table record. Suppose you wanted to populate a picklist with names from the Customer table. You would not construct a view that contained every field--you would only want to get and show the customer name field. So your view would have only one column (customer name) in it.

Another way to think about this is having multiple views of the same table each of which is accessed through a separate role. An employee table could have one view containing only employee name and contact information, one view with payroll information, and another view with human resource notes. You could access one of these views only if you belonged to a role that allowed such access.

Is There a Default View or Must I Construct a View? In theory, you might be able to use the QuickBase default view feature to get your data displayed. When you create a new field, by default the checkbox “Include in views by default” is set. (Built-in fields have this turned OFF by default.) So the default view will show all of the fields unless you uncheck the ones you don’t want displayed. In practice, though, you should expect to build one or more views.

How Do I Construct a View? Detailed instructions for constructing views, reports, and queries are provided in the video in Figure 3-2. However, what you generally need to do is create a new report by going to the main application dropdown menu and selecting Customize->Create a new...->Report. This opens the Report Builder form where you create your report. In the form, under the title “Columns to Display” select the option button titled “Custom Columns.” That will open up a display area where you can specify the view by specifying which columns to show. Notice that you always create a view in the context of a specific report.

What is a Report and How is it Related to a View? In the QuickBase UI, you use a report to specify filter criteria for which records are to be retrieved. Each report has its own view. In short, the report and view work together to get and show only the specified records and specified columns (fields) within those records. When you save a report, you have the option of saving it as a shared report. This saved report is available for use in API queries: it has a query ID (qid) and queryname (qname) that can be referenced in an API query instead of using a query string. The saved report is called a saved query in the API documentation. IMPORTANT When you save the shared report, you can allow all application users access to it, or you can restrict user access by allowing only a specific role to access it.

How is an API Query Related to Reports and Views? The API query combines the features of both reports and views. The query has a query string parameter for specifying which records are returned and a column list for specifying the columns returned (the view). The API query also has other options that mimic what you can do inside the UI with Report Builder.

Video: Constructing Reports, Views, Queries The brief video below shows how to build reports, views, and API queries.

Figure 3-2

Video: Views, Reports, and Queries

Cl ick to Add or See Comments The Components of a Query A query is typically includes the following parameters: •

Query string

•

Column list

•

Sort list

•

Options

•

Format

How to Supply the Query Parameter The query parameter is the main parameter in a query because it determines which records will come back. In contrast, the other parameters affect the “look” of the query results or further narrow the query results in some way. The Components of a Query 23 (c) 2008 Intuit Inc. All rights reserved.

There are two ways to provide the query string: •

Construct your own query string inside the <query></query> tag

•

Reference a saved query string using the <qid> or <qname> tags

Constructing the Query String When you construct a query you must build at least one query string. A query string is composed of a field ID (fid), comparison operator, and the value to be compared against (see for a list of available operators). Each of these components of the query string are separated by a period, and the whole query string enclosed in curly braces, like this: {'fid'.operator.'matching_value'}

Here is a filled-in example inside the XML tags: <query>{'5'.CT.'Ragnar Lodbrok'}</query>

Which means, “give me all the records where the “fid 5” field contains the value “Ragnar Lodbrok.” You can AND or OR several of these query strings together, separating the query strings with AND or OR, depending on your needs: <query>{'5'.CT.'Ragnar Lodbrok'}AND{'7'.CT.'Acquisitions'}</query>

Here’s the same thing as the above XML, but as you would include in a URL &query={'5'.CT.'Ragnar Lodbrok'}AND{'7'.CT.'Acquisitions'}

You can get the fids for a table by calling API_GetSchema, or from any call to API_DoQuery that sets the <fmt> parameter to “structured.”

Table 3-1

Query comparison operators

Comparison Operator

Description

Contains

XCT

Does not contain

True Value (compares against the underlying foreign key or record ID stored in relationship fields. Also used for queries on user fields.

XEX

Is not

Starts with

XSW

Does not start with

Is before

OBF

Is on or before

Is after

OAF

Is on or after

Is less than

LTE

Is less than or equal to

Is greater than

GTE

Is greater than or equal to

Referencing a Saved Query What is a saved query? In the QuickBase UI, a user customizes a report (a query is called a report in the UI) by selecting Customize->Reports. After the user saves this as a shared report, it becomes available to you as a query, assuming that there is no role restriction in place. For lack of a better term, we call this a saved query. Each saved query has an ID (qid) and also a user-supplied name (qname). Creating a saved query can be an easy and quick way to construct a query, compared to constructing a query string yourself. To use a saved query, you just refer to it by its qid (e.g., <qid>3</qid>) or by the name you gave it when you saved it (e.g., <qname>My Custom View</qname>. For the qname value, notice that you donâ&#x20AC;&#x2122;t replace blank space between words with underscore. How do you get a queryâ&#x20AC;&#x2122;s qid or qname? Any invocation of API_DoQuery that uses the <fmt> param set to structured will return a list of all saved queries inside a <queries> aggregate, including their qid and qnames. You can also use API_GetSchema to get the qid or qname. NOTE QuickBase tables have two default saved queries: List All, and List Changes.

Column List (clist) Parameter The clist specifies which columns will be included in each returned record and how they are ordered in the returned record aggregate. Here’s what a clist looks like: <clist>4.7.9.11</clist>

or in URL-ese: &clist=4.7.9.11

where each number is the fid of the field (column) you want returned, with a period separating the fids. The columns will be listed in the returned record in the same order as they appear in the clist. If you don’t specify a clist, you’ll get your table’s default columns and order. If no column list parameter is supplied, then the default report layout and field order is used. NOTE To change the default field order, select your table in the main application menubar, then click Customize->YourTableName Table->Forms->Edit the layout of the form. Select the field you want to move (or remove!) in the list, and click the Up, Down, or Remove button.

Sort List (slist) Parameter The slist determines the order in which the returned records are displayed. Here’s what an slist looks like: <slist>7</slist>

This slist sorts all records by the field whose fid is 8. This is a basic sort that you could use to sort, say, all invoices by a customer name field. But what if you wanted to further sort the invoices under each customer name by invoice number? Just specify the next sort to follow the first sort: <slist>7.12</slist>

and, for URLs: &slist=7.12

with periods separating each fid. In this example, the records are sorted by the fid 7 field, then the fid 12 field. In our example, you’d have each customer’s invoices listed together, ordered by invoice number.

If you don’t specify the sort list, then the default sort specified on the Report Layout page determines the order in which records are displayed.

Options Parameter You use the options parameter to further control the return of records. You can use any or all of the options, separating the options with a period. Here are the available options: •

num-n specify a maximum of n records in the return

•

onlynew return only those records marked with new or updated flags

•

skp-n skip the first n records returned by the query

•

sortorder-A for ascending sorts

•

sortorder-D for descending sorts

Here is a sample options parameter in both flavors, XML and URL: <options>num-15.sortorder-A.skp-15</options> &options=num-15.sortorder-A.skp-15

This sample parameter tells QuickBase to skip the first 15 records the query would normally return and give you the next 15 records and to do any sorts in ascending order. The num-n and skp-n options could be used for iterating through a bunch of records. If you don’t supply the options parameter, by default the records are sorted in ascending order and the number of records returned will be the same number as the QuickBase is set to return. NOTE The onlynew parameter produces a different result for each user that is logged into QuickBase: it won’t work with the QuickBase anonymous user.

Format Parameter: Structured vs. Unstructured One useful feature you’ll want to use in the API_DoQuery call is the <fmt>structured</ fmt> parameter. By default the query returns are not structured. Basically, you’ll just get the table name, any DBVars, and the record data with the fields you specified, all with the field names, like this: <record> <business_phone_number>(123) 103-1234 x12345</business_phone_number> <email>b@c.com</email> <file>car.jpg</file> <text>justatest</text> <update_id>1206568990479</update_id> </record

In contrast, if you specify structured returns via the <fmt> param, you’ll get fids instead of field names, and, for file attachments, you’ll also get the URL you can use to retrieve them. You don’t get those URLs in unstructured mode. (For an alternative way to download files without this URL, see “Downloading Files.”) <record> <f id="5">112149.bhsv</f> <f id="6">(650) 123-1234</f> <f id="7">cu@later.com</f> <f id="22"> Model_T.jpg <url>https://demo.quickbase.com/up/bdb5rjd6g/g/rz/ey/va/Model_T.jpg</ url> </f> <update_id>1206568990479</update_id> </record>

Using structured format, you’ll also get some of the same information about the table as if you called API_GetSchema: table dbid, metadata information, a list of all saved queries you can use, the field properties (including field help, which could be used for tooltips) and the default values for all the fields you asked for in your query. Then, in the field returns themselves, the field data is presented in a more compact form so you can immediately spot the fid and the actual field value.

Cl ick to Add or See Comments Sample Queries To query a particular field: {'7'.XCT.'Fred'}

To query any field: {'0'.OAF.'3/31/01'}

To combine multiple query strings: {'9'.SW.'Wilma'}OR{'10'.XSW.'Dino'}

To query for records owned by the current user: {'4'.TV.'_curuser_'}

To query for records modified by the current user: {'5'.TV.'_curuser_'}

CHAPTER 4 UPLOADING AND DOWNLOADING FILES

1 1

QuickBase applications can support file attachment storage and file attachment access through the API’s file upload and download feature. Files are “attached” through a record field that has the type File. File attachments are stored in a special database that is separate from the QuickBase application database. That means they won’t hog up space in the QuickBase application database. NOTE This section describes the typical upload scenario where access to the local file system is available if needed. If your environment cannot make use of the local file system (such as Flex), you may need to use the API_UploadFile call.

Uploading Files Files are uploaded as file attachments to a record during an API_AddRecord or API_EditRecord call. The file field you use for file attachments must be of type File. The file must be base64 encoded. The trick is to NOT use MIME style encoding with newline characters at a maximum line length of 76. Instead, QuickBase requires you omit these newlines. If you don’t omit the newlines, the stored file in QuickBase won’t be usable. The SendApiCalls sample, included with QuickBase SDK, contains an example of how to base64 encode the QuickBase-friendly way in .NET. Because of the typical file sizes, you won’t be able to upload files using a URL. You’ll have to POST the encoded file as XML. For details, see the language reference entries for “API_AddRecord” and “API_EditRecord”.

Downloading Files There are two ways to download a file. The first and easiest way to download an attached file can be used if you know the database ID, the record ID, the Field ID of the file field you are attaching to, and the version ID. To use this type of download, you use a GET request using this URL format: https://www.quickbase.com/up/DBID/a/rRID/eFID/vVID

replacing DBID with your TABLE dbid (not the application dbid!) , RID with the rid of the record with the File attachment, FID witht the fid of the File attachment field, and VID with the version ID of the file. Specifying 0 (zero) for the VID always gets you the most recent version. https://www.quickbase.com/up/bdb5rjd6h/a/r13/e8/v0

NOTE If you use file attachments, you should know about the QuickBase version feature. Take a peek at the QuickBase online help for more information.

An alternate way to get the file is to use a different GET. This way uses a GET containing the URL of the file attachment, using no IDs other than the table dbid. The trick is getting the URL of the file attachement. How do you get that? You get the file attachment URL back from a call to API_DoQuery if you set its <fmt> parameter to “structured.” (The URL comes back, surprisingly in the <url></url> tags) Here’s a typical URL that you would use in this second way of doing a GET: https://www.quickbase.com/up/bdb5rjd6g/g/rz/ey/va/Model_T.jpg

Cl ick to Add or See Comments

CHAPTER 5 HTML API LANGUAGE REFERENCE

1 1

This chapter provides detailed descriptions of each API call in the HTML API.

Order of Parameters in API Calls (XML or URL) QuickBase accepts API call parameters in any order whether the call comes in as an XML POST or as a URL GET.

How to Understand the XML Samples This document has the XML samples in this kind of format: POST https://www.quickbase.com/db/bddnc6pn7 Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddField <qdbapi> <label>label</label> <type>type</type> <mode>mode</mode>  <ticket>ticket</ticket> <udata>whatever</udata>  </qdbapi>

There are two parts you need to supply when using the XML form of the API call: POST https://www.quickbase.com/db/bddnc6pn7 Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddField

The first three of these lines are standard HTTP headers for the POST request method. The first is the URL for the POST: this is the path to the destination using secure https. The dbid is the last part of the path. For some calls, this will be replaced by /main, and will be called out in the documentation. The last line is a custom header that QuickBase expects containing the API call itself. The second part is the XML payload of the HTPPS POST request:

<qdbapi> <label>label</label> <type>type</type> <mode>mode</mode>  <ticket>ticket</ticket> <udata>whatever</udata>  </qdbapi>

The elements between the <qdbapi> tags are the parameters: these are documented for each API call.

Some Optional API Input Parameters The documentation for each API call lists the parameters. However, there some generally available options that are not listed in the API call documentation itself that weâ&#x20AC;&#x2122;ve included here for completeness.

Table 5-1

Optional parameters

Parameter

Value

Description

encoding

A string that specifies the encoding parameter of the XML output

The QuickBase API outputs XML using the Unicode character set. However if you are using Shift-JIS as your character encoding for a particular QuickBase table then you'll want to specify the encoding parameter on every call you make to the QuickBase HTML API to ensure that the character encoding of the XML response is properly set. Example output below: <?xml version="1.0" encoding="shift_jis" ?>

rdr

A URL to redirect to if there is no error

No default. If absent, no redirection is done. If present and there is an error, QuickBase will always redirect to a standard error page. Redirect URLs often have query strings in them that cause interference unless they are properly escaped. Use %3D for equals, %3F for question marks, and %2 for ampersands.

xsl

A URL that points to an XSL document that is referenced in the XML output from the call

Usually is omitted, in which case the XML return page does not include any reference to an XSL document. XSL URLs often have query strings in them that cause interference unless they are properly escaped. Use %3D for equals, %3F for question marks. Ampersands have special significance in XML so they can’t be used in URLs for XSL style sheets. QuickBase understands carets as a replacement for ampersands when delimiting name/value pairs in query strings. Therefore, don’t use ampersands even in escaped form. Use the caret symbol in escaped form instead: %E. For example: ?act=dbpage&pagename=mypage.xsl becomes %3Fact%3Ddbpage%Epagename%3Dmypage.xsl

Figure 5-1

Some parameters available to (almost) all API calls

Cl ick to Add or See Comments

API_AddField Header and XML POST https://www.quickbase.com/db/bddnc6pn7 Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddField <qdbapi> <label>label</label> <type>type</type> <mode>mode</mode>  <ticket>ticket</ticket> <udata>whatever</udata>  </qdbapi> URL alternative https://www.quickbase.com/db/ 6mpjiez8?act=API_AddField&label=Phone+Number&type=phone&ticket=2_bdh78chd4_ dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25

Usage You invoke this call on a table-level dbid to add a new field to the table you specify. After you add the field, you’ll need to use API_SetFieldProperties to set the properties of the new field and any default values. Once you pick the field type using this call, you won’t be able to change the field type later using API_SetFieldProperties. You’ll only be able to change the field type from the QuickBase UI.

Request Parameters The following parameters are available: Parameter

Value

Required?

label

The name of the new field.

yes

type

Specify the QuickBase field type. The eligible type names differ slightly from their counterparts in the QuickBase UI:

yes

QuickBase Type (UI)API type CheckBoxcheckbox Database Linkdblink Datedate Durationduration Email Addressemail File Attachmentfile Formulasee the “mode” param Lookupsee the “mode” param Numericfloat Numeric-Currencycurrency Numeric-Ratingrating Phone Numberphone Relationshipfkey Texttext Time Of Daytimeofday URL-Linkurl mode

If you want the field to be a formula field, specify the value “virtual.” You can specify this for any field type. (type can be set to any value.)

Required for lookup or formula fields

If you want this field to be a lookup field, specify the value “lookup.” You can only specify this if type is set to a text or numeric type. ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

Element Name

Value

fid

The field ID. You can use this value in other API calls that manipulate this field or field values, such as setting properties (API_SetFieldProperties). You can also get this field ID by invoking API_GetSchema on the table.

label

The name you want to display for this column. This is the name of the field as it appears in the QuickBase application UI. Notice that you can derive the field name from the label by lowercasing it and replacing all non-alphanumeric values (including the space character) with underscore. (Example: the label “Vehicle Number” converted to “vehicle_number” can be used as the field name. Field name is useful because it can be used instead of fid in most API calls and is easier to remember.

udata

Optional. Contains any udata value supplied in the request.

Example XML Request POST https://www.quickbase.com/db/6mpjiez8? Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddField <qdbapi> <label>Phone Number</label> <type>phone</type> <ticket>1_6c6482m9_j36_c7mdvh9cmmtn9c8qtr5qchvw33v</ticket> </qdbapi>

Example Response <?xml version="1.0" ?> <qdbapi> <action>API_AddField</action> <errcode>0</errcode> <errtext>No error</errtext> <fid>8<fid> <label>Phone Number</label> </qdbapi>

Cl ick to Add or See Comments

API_AddRecord Header and XML POST https://www.quickbase.com/db/6c5xatxy HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_AddRecord Using Field Names <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <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> Using Field IDs <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <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>

Usage You invoke this call on a table dbid to add a record to that table by specifying fields and their values. You don’t have to set all field values but you must set all required fields or the call returns an error.

Fids vs. Field Names You specify the field values using field/value pairs, using either field names or field IDs (fid). field name

fid

Easier to use (easier to remember) than fids. Also, during design phase you may break one table out into several tables, which will change fid values. The field name won’t change if you keep the same label.

The field name is the label converted to all lowercase and with an underscore replacing blank space and non-alphanumeric characters. For example the field label “Vehicle Name” becomes “vehicle_name.”

Used in many API calls that manipulate fields. Normally can be substituted with field name. Fids and field names can coexist in the same API call request.

The fid for a field can be obtained from a call to API_GetSchema or from the QuickBase field customization UI (if you’re an administrator)

To get the label you can use your memory, or if that fails, API_GetSchema, or the application UI within QuickBase.

What Happens If I Write to Built-In Fields? Every table has the same built-in QuickBase fields, for example, Record ID. If you mistakenly write to one of these fields you’ll get an error and the record won’t be added, unless you use the handy ignoreError parameter in your API call. What Happens if I Write to Non-Writable Fields? If you write to fields not meant to be written to, such as formula fields, the iCalendar field, the vcard field, and so forth, what happens? If your API call writes to valid fields, those fields will get written to and the record will be added successfully. Writes to the non writable fields are ignored. How Do I Get Data Into a vCard or iCalendar? vCard and ICalendar are widgets linked to fields in a table. You need to write the data to those table fields and the vCard and iCalendar automatically get that data. Adding a Record Without Supplying Data for All Fields You must supply field data for all required field or you’ll get a runtime error. However, if fields are not marked as required and you don’t supply values for them in your API_AddRecord call, those fields will get the defaults you assigned to them when you set the field properties. How Do I Upload a File When I Add My Record? File uploading is covered in detail in the topic on “Uploading Files”

What Data Validation Is Enforced on Field Data I Write? Currently, you need to supply your own validation, since the API layer is pretty liberal in this area. For example, in a field of type Email, you can supply the value â&#x20AC;&#x153;Harry Breeksâ&#x20AC;? and QuickBase will obligingly add that as the email address.

However, in some cases, values in incompatible format will simply not be written to the record. For example suppose you supply the value “Charles” for a field of type Numeric. Or, suppose you also supply an arbitrary value such as “My dog Elroy” for a field of type Phone. Neither Charles nor your dog Elroy will be written to the record, but that won’t stop Quick Base from adding the record.

Request Parameters

The following parameters are available: Parameter

Value

Required?

field

You specify this using either the fid attribute or the name attribute of the <field> element. For example:

yes

<field fid=”18”>Hi!</field> <field name=”Message”>Hi!</field> You must specify all required fields. To supply a File Attachment field, you first need to base64 encode it. The file encoding you must do is not MIME type encoding where you insert newline at the 76th character. You must not insert any newline characters when you base64 encode the file! There must be no MIME headers. Many base64 encoders or base64 encoding methods are for MIME type encoding and will not work with QuickBase. If your file attachments upload OK, but don’t display in QuickBase, doublecheck for presence of the newline. Next, in the opening <field> tag, insert the “filename” attribute in addition to the fid or name attribute like this: <field fid=”22” filename=”profilePhoto.jpg”>. The “filename” attribute value should be set to the name of the file WITHOUT any path, just as shown above. Then, between the <field fid=”myfid” filename=”myFile.whatever> tag and the end tag </field>, you insert the base64 encoded text from the encoded file. Date values should be passed in formatted as MM-DD-YYYY or as milliseconds since January 1st, 1970 00:00:00 GMT. Note that the QuickBase HTML API returns dates as milliseconds since January 1st, 1970 00:00:00 GMT which is the same internal representation used by JavaScript. Phone Number fields require the use of four characters “.xx.” to delimit a phone number from its extension. So the phone number 978-5551122 x123 would be passed in as 978-5551122.xx.123 to API_AddRecord. For fields of type user, supply the user’s email address or the userid. disprec

Specify <disprec /> if you want to display the new record within the QuickBase application. There may be an application login required before the record can be displayed.

Parameter

Value

Required?

fform

Specify <fform /> if you are invoking this from within an HTML form that has checkboxes and you want those checkboxes to set QuickBase checkbox fields.

ignoreError

Specify a value of 1 for this parameter to suppress the error that is returned when a builtin field (for example, Record ID#) is written-to in an API_AddRecord call. If this is not specified, by default, an error is returned in the above scenario.

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

rid

Record ID of the record that was added

update_id

This parameter is 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.

Example XML Request The following request contains a truncated file in base64 encoding. The file is truncated so it won’t work as is. Replace it with your own encoded file. POST https://www.quickbase.com/db/6mpjiez8? Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddUserToRole

<qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <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> </qdbapi>

Example 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>

Cl ick to Add or See Comments

API_AddReplaceDBPage Header and XML POST https://www.quickbase.com/db/bddnc6pn7 Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddReplaceDBPage <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <userid>112245.efy7</userid> <roleid>10</roleid> <udata>whatever</udata>  </qdbapi> URL alternative Because URLs can only be about one thousand characters in length this is not the recommended way to make this API call

Usage You invoke this call on an application dbid to add a new database page or to replace an existing page with a new page. The QuickBase allows you to store various types of pages at the application level. These pages can be user guide pages accessible from the QuickBase Help, they can be various text or rich text or HTML page that you store and link to buttons in the QuickBase UI. They can also be XSL templates used for customizing the QuickBase application, or Exact Forms. Exact Forms are forms (form letters, invoices, etc.) created in Microsoft Word using the QuickBase Exact Form template that get data from QuickBase tables. (For more information about these stored pages, see the QuickBase online Help.)

Request Parameters Table 5-2

Request Params

Parameter

Value

Required?

pageid (if replacing)

If you are replacing a database page, specify its page ID here. QuickBase will replace that page with the page you supply in <pagebody>.

yes

or pagename (if adding)

If you are adding a new page, specify the pagename. pagetype

1 – for XSL stylesheets or HTML pages.

yes

3 – for Exact Forms. pagebody

This is the element containing the contents of the page you are adding.

yes

ignoreError

Not used.

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

pageid

The page identifier of the page that was added or replaced.

Example XML Request <qdbapi> <pagename>newstylesheet.xsl</pagename> <pagetype>1</pagetype> <pagebody> <?xml version='1.0'?> &lt;xsl:stylesheet xmlns:xsl=&quot;http://www.w3.org/1999/XSL/Transform&quot; version=&quot;1.0&quot;&gt; &lt;xsl:template match=&quot;/&quot;&gt; &lt;html&gt; API_AddReplaceDBPage 47 (c) 2008 Intuit Inc. All rights reserved.

&lt;head&gt; &lt;/head&gt; &lt;body&gt; Hello World &lt;/body&gt; &lt;/html&gt; &lt;/xsl:template&gt; &lt;/xsl:stylesheet&gt; </pagebody> <ticket>1_6c644sum_j36_3rsmdrbhm83c75jfb8di27qiz</ticket> </qdbapi>

Example Response <?xml version="1.0" ?> <qdbapi> <action>API_AddReplaceDBPage</action> <errcode>0</errcode> <errtext>No error</errtext> <pageID>6</pageID> </qdbapi>

Cl ick to Add or See Comments

API_AddUserToRole Header and XML POST https://www.quickbase.com/db/bddnc6pn7 Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddUserToRole <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <userid>112245.efy7</userid> <roleid>10</roleid> <udata>whatever</udata>  </qdbapi> URL alternative https://quickbase.com/db/ bdb5rjd6h?act=API_AddUserToRole&userid=112149.bhsv&roleid=11&username=Lodbr ok&password=snakes

Usage Access to your application is governed by the roles in effect for your application. Users can access your application only if you assign them to one (or more) of the these roles. You assign a user to a role using this call. A common use of this call is to set up a second call, API_SendInvitation, where you let the user know that the user can access the application. If you want a user to have several roles, you can invoke this on the same user several times, each time specifying a different role. Although an application can use the standard default roles (viewer, participant, administrator), each application can have its own set of roles, with the access and permissions per role set up as needed by that particular application. You can find out what the roles are for the current application by calling API_GetRoleInfo. In order to make this call, you have to have administrator-level access in the application. See also â&#x20AC;&#x153;API_ProvisionUserâ&#x20AC;? for an alternate way to assign roles to users.

Request Parameters Table 5-3

Request params

Parameter

Value

Required?

userid

The userid of the user to be added to the access role.

yes

roleid

The ID of the access role being assigned to the user.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Example XML Request POST https://www.quickbase.com/db/6mpjiez8? Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_AddUserToRole <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <userid>112245.efy7</userid> <roleid>10</roleid> <udata>whatever</udata>  </qdbapi>

Example Response <?xml version="1.0" ?> <qdbapi> <action>API_AddUserToRole</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>whatever</udata> </qdbapi>

Cl ick to Add or See Comments

API_Authenticate Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_Authenticate <qdbapi> <username>PTBarnum</username> <password>TopSecret</password> <hours>24</hours> <udata>optional data</udata> </qdbapi>

URL Alternative https://www.quickbase.com/db/ main?act=API_Authenticate&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx 7ty25&hours=12

Usage IMPORTANT You should always use HTTPS (not HTTP) when calling API_Authenticate. Otherwise you’ll be sending the login data out “in the clear” where it can be seen and used by anyone.

You invoke this call on \db\main (no dbid) to get a ticket. This call validates the supplied user name and password, and, if successful, returns a ticket that is supplied in subsequent API calls. The ticket is valid for eight hours, unless you specify a different value in the <hours> parameter. In addition to the ticket, a cookie is also returned with the name TICKET. This is the only API call that returns a ticket cookie. API_Authenticate is the SDK equivalent of logging into QuickBase. Remember that merely logging into QuickBase by itself does not give you access rights to even a single QuickBase application. You must first be assigned a role in the application by someone who has administrator rights. The same holds true with the ticket you get from this call. By itself, the ticket returned from this call does not confer ANY access rights to any QuickBase application. The user has to be given a role first, either by API_AddUserToRole or by API_ProvisionUser.

Request Parameters Parameter

Value

Mandatory?

username

This is the user’s email address registered with QuickBase or the screen name that was selected within QuickBase when the user registered.

yes

password

The user’s QuickBase password

yes

hours

The number of hours that the ticket will be valid. If not supplied the validity period is 8 hours.

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

ticket

The ticket needed for application access.

userid

The ID of the current user. The user ID is required for some API calls, so it is a good idea to save this. The userID persists from session to session.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <username>PTBarnum</username> <password>TopSecret</password> <hours>24</hours> <udata>optional data</udata> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_authenticate</action> <errcode>0</errcode> <errtext>No error</errtext> <ticket>2_beeinrxmv_dpvx_b_crf8ttndjwyf9bui94rhciirqcs</ticket> <userid>112245.efy7</userid> </qdbapi>

Cl ick to Add or See Comments

API_ChangeRecordOwner Header and XML POST https://www.quickbase.com/db/6c5xatxy HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_ChangeRecordOwner <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <rid>3</rid> <newowner>Muggsy</newowner> <udata>mydata</udata> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6c5xatxy?act=API_ChangeRecordOwner&rid=3&newowner=Muggsy&username=PTBarnum& password=TopSecret

Usage The record owner, by default, is the user who created it. QuickBase can use record ownership to restrict access. Normally this is done through roles, where a role can be set up to restrict view and/or modify access to the record owner. In this scenario, it can be desirable to transfer record ownership from one user to another; for example, in a tech support application you might want to transfer ownership of a support incident (record) from one tech support rep to another. What this call does is allow you to assign another user to be the record owner. In order to call this, you must have application administrator rights.

Request Parameters Parameter

Value

Mandatory?

rid

The record ID. Every record in every table has a unique rid. However, in order to actually get the rid from a query requires you to specify the record ID field in the clist that you use when you issue the query (API_DoQuery).

yes

newowner

The user to whom you are transferring ownership. You can specify the userâ&#x20AC;&#x2122;s screen name or email address, depending on which is handier.

yes

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <rid>3</rid> <newowner>Muggsy</newowner> <udata>mydata</udata> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_changerecordowner</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> </qdbapi>

Cl ick to Add or See Comments

API_ChangeUserRole Header and XML POST https://www.quickbase.com/db/6c5xatxy HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_ChangeUserRole <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <userid>112248.5nzg</userid> <roleid>11</roleid> <newRoleid/> </qdbapi></qdbapi>

URL Alternative https://www.quickbase.com/db/ bdb5rjd6h?act=API_ChangeUserRole&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6 vt6kfdx7ty25 &userid=112245.efy7&roleid=10&newRoleID

Usage This calls allows you to assign a user to a new role, possibly to upgrade or downgrade access, or simply to move the user to a different role. You also use this call to assign the user to a special role called “None” which doesn’t allow the user any access to the application. This may not seem so special from the user perspective, but the “None” role allows the administrator to disable access while retaining the user on the application user list. (In the QuickBase UI Manage Users page, this kind of user shows up in the user list with the role of “None.”) Even if the user has a role of None, a call to API_UserRoles will return this user in the list of users for your application. This could be convenient for moving that user into some other role at a later time.

Request Parameters Parameter

Value

Mandatory?

userid

The user ID.

yes

roleid

The user’s current role in the application

yes

newroleid

If this parameter is supplied but is left blank, (for example, <newroleid />) the call sets the user to a role of “None”

yes

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <userid>112248.5nzg</userid> <roleid>11</roleid> <newRoleid>10</newroleid> </qdbapi></qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_changeuserrole</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_CloneDatabase Header and XML POST https://www.quickbase.com/db/bddnc6pn7 HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_CloneDatabase <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <udata>mydata</udata> <newdbname>Mit Data</newdbname> <newdbdesc>Datbase clone with cloned data too</newdbdesc> <keepData>1</keepData> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bdb5rjd6h?act=API_CloneDatabase&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6v t6kfdx7ty25 &newdbname=HarryBreeks&newdbdesc="clone it all"

Usage This call makes a complete clone of the specified source application, schema, views, users, and so for. Optionally, using the keepData parameter, you can clone the data as well. If you donâ&#x20AC;&#x2122;t want to carry over some or any of the users in the original application, after you clone the database you can invoke API_RemoveUserFromRole on the clone to remove any user you want omitted.

Request Parameters Parameter

Value

Mandatory?

newdbname

Specify the name you want the new application to have.

yes

newdbdesc

Specify the description for the new application. This will be displayed in the Info for the application.

yes

keepData

If you want to clone the data from the source database, include this parameter and set it to 1 (one). The new application will contain the same data as the original application.

If you want only the same schema, views, user list as the original database, but NOT the data, simply omit this parameter.

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

newdbid

The database ID of the new database.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <udata>mydata</udata> <newdbname>Kein Data</newdbname> <newdbdesc>Datbase clone with No cloned data</newdbdesc> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_CloneDatabase</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <newdbid>bddnc6pn7</newdbid> </qdbapi>

Cl ick to Add or See Comments

API_CreateDatabase Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_CreateDatabase <qdbapi> <dbname>FueldCharter</dbname> <dbdesc>Vehicle and Fuel Cost Tracker</dbdesc> <ticket>2_bdb62qmgr_dpsx_b_gwae5hcqrpue4wfchactwq8am</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ main?act=API_CreateDatabase&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kf dx7ty25 &dbname=FuelCharter&dbdesc="Vehicle and Fuel Cost Tracker"

Usage This call creates a new QuickBase application with the main application table populated only with the built in fields. Youâ&#x20AC;&#x2122;ll need to add desired fields using API_AddField, set field properties using API_SetProperties, and optionally add more tables to your application using API_CreateTable. (Or, just use the QuickBase UI to do all this.) Notice the dbid that gets returned in the response, if all goes well. This is the applicationlevel dbid. Some API calls require the use of the application-level dbid, and some require a table-level dbid. Calls requiring application-level dbids are application wide calls, such as API_ChangeUserRole. Calls requiring table-level dbid are those that manipulate tables, such as API_AddField or API_AddRecord. How do you get the table level dbid? API_GetSchema returns the dbids of all child tables (if you use the application-level dbid!). Typically, these dbids differ significantly from the main application dbid. However, the main child table, which is built with the application by the API_CreateDatabase call, can be nearly identical to the application-level dbid. They might only differ by one terminal character, which can be confusing.

Request Parameters Parameter

Value

Mandatory?

dbname

The name of the new application

yes

dbdesc

The description for the new application.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

dbid

The application-level dbid of the new application.

Sample XML Request <qdbapi> <dbname>FueldCharter</dbname> <dbdesc>Vehicle and Fuel Cost Tracker</dbdesc> <ticket>2_bdb62qmgr_dpsx_b_gwae5hcqrpue4wfchactwq8am</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_CreateDatabase</action> <errcode>0</errcode> <errtext>No error</errtext> <dbid>bddnn3uz9</dbid> </qdbapi>

Cl ick to Add or See Comments

API_CreateTable Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_CreateTable <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <pnoun>Vehicle</pnoun> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddfa5nbx?act=API_CreateTable&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6 kfdx7ty25 &pnoun=Vehicle

Usage If you have application administration rights, you can use this call to create a child table for that application. The dbid you supply must be an application-level dbid, not a table-level dbid. The pnoun parameter is where you specify the table name. Each table name must be unique within the application. If you supply a duplicate name (or use the default more than once) you will get an error.

Request Parameters Parameter

Value

Mandatory?

pnoun

The name you want to use for the name of the table. Typically you want to use a name that could apply to each individual record in the table. For example, if each table row contains information about vehicles your company owns, you might want to use “Vehicle” as your table name.

no, but recommended

If you don’t supply this, the name Records is assigned by default. Because your application requires unique table names, you’ll only be able to use the default once. Successfully, that is.

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

newdbid

The dbid of the new table.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <pnoun>Vehicle</pnoun> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_createtable</action> <errcode>0</errcode> <errtext>No error</errtext> <newDBID>bddfa5nbx</newDBID> </qdbapi>

Cl ick to Add or See Comments

API_DeleteDatabase Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_DeleteDatabase <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6mpjiez8?act=API_DeleteDatabase&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6v t6kfdx7ty25

Usage If you have application administration rights, you can use this call to delete either a child table or the entire application, depending on the dbid you supply. If you supply the application-level dbid you delete the application. If you supply a table-level dbid you delete the table.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

Element Name

Value

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_DeleteDatabase</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_DeleteField Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_DeleteField <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <udata>whatever</udata>  </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6mpjiez8?act=API_DeleteField&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6k fdx7ty25

Usage If you have application administration rights, you can use this call to delete a table field. You have to use a table-level dbid. If you use an application level dbid youâ&#x20AC;&#x2122;ll get an error 31, No such field. This call will delete the field for all records, whether there is data in it or not, and there will be no warning message.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_DeleteField</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_DeleteRecord Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_DeleteRecord <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <rid>2</rid> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_DeleteRecord&rid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372 j5rb6vt6kfdx7ty25

Usage If you have application administration rights, you can use this call to delete a table record. You have to use a table-level dbid. If you use an application level dbid you’ll get an error. If you want to delete several records at one time, you might want to use API_PurgeRecords.

Request Parameters Parameter

Value

Mandatory?

rid

The record ID of the record to be deleted. You can get the recordID of any record in a query. (See “API_DoQuery”)

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <rid>2</rid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_DeleteRecord</action> <errcode>0</errcode> <errtext>No error</errtext> <rid>2</rid> </qdbapi>

Cl ick to Add or See Comments

API_DoQuery Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_DoQuery <qdbapi> <ticket>2_bdd6zutr5_dpsx_b_2wydyzcz5v287ccdfzdwfcsmj4</ticket> <udata>mydata</udata> <query>{'5'.CT.'Ragnar Lodbrok'}AND{'5'.CT.'Acquisitions'}</query> <clist>5.6.7.22.3</clist> <slist>3</slist> <options>num-4.sortorder-A.skp-10.onlynew</options> <fmt>structured</fmt> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6c5xatxy?act=API_DoQuery&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7 ty25&query={'6'.CT.'done'}AND{'14'.CT.'USA'}&clist=7.8&slist=6&options=sort order-A

Usage You invoke this call on a table dbid to get records from the table. You can use this call to get all the records and all the fields, but typically you would want to get only some of the records and only those fields you happen to care about, ordered and sorted the way you need them to be. For More Information on QuickBase Queries... We only cover the most basic information on queries here, as is customary in a language reference section. However, there are a number of useful details and background info awaiting you over at the topic “Building and Using Queries” : be sure to take a peek at it. About API_DoQuery Parameters You’ll need to supply these parameters to get exactly the data you need: •

query Query string: you can supply the <qid> or <qname> of a saved query if you want to use a shared report in the QuickBase UI. Or you can specify <query> to construct your own query string. For details see “How to Supply the Query Parameter”.

•

<clist> Column list: specifies which columns will be returned. For details, see “Column List (clist) Parameter”.

•

<slist> Sort list: specifies how the returned records will be sorted. For details, see “Sort List (slist) Parameter”.

•

<options> Options: lets you specify the number of records to return at a time, number of returned records to skip, ascending or descending sort order, etc. For details, see “Options Parameter”.

•

<fmt> Format: lets you specify whether the return uses field names or fids, etc. For details, see “Format Parameter: Structured vs. Unstructured”.

Query Operators You can use a saved query (see “Referencing a Saved Query”) to specify which records are returned, referencing this query by ID (qid) or by name <qname>. If you construct your own query string inside the <query></query> tag you’ll need to take a look at Table 5-5 for a list of available operators. Here’s what the basic query string looks like: {'fid'.operator.'matching_value'}

Here are some filled-in examples, inside the XML tags and the URL version: <query>{'5'.CT.'Ragnar Lodbrok'}</query> &query={'5'.CT.'Ragnar Lodbrok'}

Each of these components of the query string are separated by a period, and the whole query string enclosed in curly braces. You can AND or OR several of these query strings together, separating the query strings with AND or OR, depending on your needs:

Table 5-4

.Comparison operators

Comparison Operator

Description

Contains

XCT

Does not contain

True Value (compares against the underlying foreign key or Record ID# stored in relationship fields). Also is used for queries on user fields.

XEX

Is not

Starts with

XSW

Does not start with

Is before

OBF

Is on or before

Is after

OAF

Is on or after

Is less than

LTE

Is less than or equal to

Is greater than

GTE

Is greater than or equal to

Table 5-5

Comparison operators for query strings

Request Parameters Parameter

Value

Mandatory?

query or qid or qname

Use <query>{myfid.operator.value}</query> if you want to construct and supply your own query string. Or,

no (returns all records if absent)

Use <qid>n</qid>if you want to use a saved query and want to use its query ID. Or, Use <qname>myQuery</qname> if you want to use a saved query and refer to it by its queryname. clist

A period delimited list of field IDs to be returned. The order you list these in is the order in which theyâ&#x20AC;&#x2122;ll be returned.

no (returns the tableâ&#x20AC;&#x2122;s default columns if absent)

slist

A period delimited list of field IDs for sorting.

fmt

Specify structured to get more table information, more compact XML return, fids instead of field names.

The default if omitted is non structured.

Parameter

Value

Mandatory?

options

num-n return a maximum of n records

onlynew return only those records marked with new or updated flags skp-n skip the first n records returned by the query sortorder-A for ascending sorts sortorder-D for descending sorts ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

records

If you don’t specify <fmt> as structured, you’ll get a dbinfo aggregate, a variables aggregate for the DBVars, and one record aggregates for each returned record If you do specify the structured format, you’ll get a <table> super-aggregate containing the following aggregates: original (table metadata such as next available fid, next available rid, create/mod dates, and some defaults) variables (all the DBVars) queries (all of the saved queries, with qid and qnames) fields (properties for every field to be returned in the query) records (contains 0-N <record> sub-aggregates containing the actual record data, using fids, not field names)

NOTE The QuickBase HTML API returns dates as milliseconds since January 1st, 1970 00:00:00 GMT which is the same internal representation used by JavaScript. The input to the API for date fields is limited to the format MM-DD-YYYY or milliseconds since January 1st, 1970 00:00:00 GMT. Multi-line Text fields are returned with each line of the text field is separated by a <BR/> tag pair.

Sample XML Request <qdbapi> <ticket>2_bdd6zutr5_dpsx_b_2wydyzcz5v287ccdfzdwfcsmj4</ticket> <udata>mydata</udata> <query> <query>{'5'.CT.'Harry Breeks'}</query> </query> <clist>5.6.7.22.3</clist> <slist>3</slist> <options>num-4.sortorder-A.skp-10.onlynew</options> <fmt>structured</fmt> </qdbapi>

Sample XML Response (structured format) <?xml version="1.0" ?> <qdbapi> <action>API_DoQuery</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <qid>-1</qid> <qname /> <table> <name>API created Sample</name> <desc>This is a sample table.</desc> <original> <table_id>bdb5rjd6g</table_id> <cre_date>1204586581894</cre_date> <mod_date>1206583187767</mod_date> <next_record_id>34</next_record_id> <next_field_id>24</next_field_id> <next_query_id>5</next_query_id> <def_sort_fid>6</def_sort_fid> <def_sort_order>1</def_sort_order> </original> <variables> <var name="Blue">14</var> <var name="Jack">14</var> <var name="Magenta">12</var> <var name="usercode">14</var> </variables>

<queries> <query id="1"> <qyname>List All</qyname> <qytype>table</qytype> <qycalst>0.0</qycalst> </query> <query id="2"> <qyname>List Changes</qyname> <qytype>table</qytype> <qydesc>Sorted by Date Modified</qydesc> <qyslst>2</qyslst> <qyopts>so-D.onlynew.</qyopts> <qycalst>0.0</qycalst> </query> </queries> <fields> <field id="5" field_type="userid" base_type="int32" role="modifier"> <label>Last Modified By</label> <nowrap>1</nowrap> <bold>0</bold> <required>0</required> <appears_by_default>0</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>1</allow_new_choices> <sort_as_given>0</sort_as_given> <carrychoices>1</carrychoices> <foreignkey>0</foreignkey> <unique>0</unique> <doesdatacopy>0</doesdatacopy> <fieldhelp /> <display_user>fullnamelf</display_user> <default_kind>none</default_kind> </field> <field id="6" field_type="phone" base_type="text"> <label>Business Phone Number</label> <nowrap>0</nowrap> <bold>0</bold> <required>1</required> <appears_by_default>1</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>0</allow_new_choices> <sort_as_given>0</sort_as_given> <carrychoices>0</carrychoices> <foreignkey>0</foreignkey> <unique>1</unique> <doesdatacopy>0</doesdatacopy> <fieldhelp>This is the phone number</fieldhelp> <num_lines>1</num_lines> <append_only>0</append_only> <allowHTML>0</allowHTML> <has_extension>1</has_extension> </field> <field id="7" field_type="email" base_type="text"> <label>Email</label> API_DoQuery 77 (c) 2008 Intuit Inc. All rights reserved.

<nowrap>0</nowrap> <bold>0</bold> <required>0</required> <appears_by_default>1</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>0</allow_new_choices> <sort_as_given>0</sort_as_given> <carrychoices>1</carrychoices> <foreignkey>0</foreignkey> <unique>0</unique> <doesdatacopy>1</doesdatacopy> <fieldhelp /> </field> <field id="22" field_type="file" base_type="text"> <label>File</label> <nowrap>0</nowrap> <bold>0</bold> <required>0</required> <appears_by_default>1</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>0</allow_new_choices> <sort_as_given>0</sort_as_given> <carrychoices>1</carrychoices> <foreignkey>0</foreignkey> <unique>0</unique> <doesdatacopy>0</doesdatacopy> <fieldhelp /> <max_versions>3</max_versions> <see_versions>1</see_versions> <use_new_window>1</use_new_window> </field> <field id="3" field_type="recordid" base_type="int32" role="recordid" mode="virtual"> <label>Record ID</label> <nowrap>1</nowrap> <bold>1</bold> <required>0</required> <appears_by_default>0</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>0</allow_new_choices> <sort_as_given>0</sort_as_given> <default_value>10</default_value> <carrychoices>1</carrychoices> <foreignkey>0</foreignkey> <unique>1</unique> <doesdatacopy>0</doesdatacopy> <fieldhelp />

<comma_start>0</comma_start> <does_average>0</does_average> <does_total>0</does_total> <blank_is_zero>0</blank_is_zero> </field> </fields> <lastluserid>0</lastluserid> <lusers> <luser id="112149.bhsv">AppBoss</luser> </lusers> <records> <record> <f id="5">112149.bhsv</f> <f id="6">(123) 333-4321 x34566</f> <f id="7">bo@co.com</f> <f id="22" /> <f id="3">12</f> <update_id>1206421031556</update_id> </record> <record> n more records here </record> </records> </table> </qdbapi>

Cl ick to Add or See Comments

API_EditRecord Header and XML POST https://www.quickbase.com/db/6c5xatxy HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_EditRecord Using Field Names <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <rid>4</rid> <field name="start_date">06-08-2008</field> <field name="attendee_name">Joseph Riesentrotter</field> </qdbapi> Using Field IDs <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <rid>4</rid> <field fid="11">06-08-2008</field> <field fid="12">Joseph Riesentrotter</field> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 57pa5vjf?act=API_EditRecord&rid=154&_fnm_second=1776&_fid_8=changed&update_ id=992017018414

Usage You can use this to change any of the editable field values in the specified record. Only those fields specified are changed; unspecified fields are left unchanged.

Request Parameters The following parameters are available: Parameter

Value

Required?

rid

Record ID of the record to be modified

yes

Parameter

Value

Required?

update_id

The update ID can be returned from the query to get the record you are editing. It is normally a good idea to use update_id if more than one user might edit the record.

By supplying this value, you’re “telling” QuickBase what you think the latest record state is. If another user has in the meantime made changes, the update ID in QuickBase will change, which will render invalid the update ID that you have. You’ll need to requery the application to get a fresh version of the record and its new update ID, then make your changes. field

yes

You specify this using either the fid attribute or the name attribute of the <field> element. For example: <field fid=”18”>Hi!</field> <field name=”Message”>Hi!</field> You must specify all required fields. To supply a File Attachment field, see “API_AddRecord”. You first need to base64 encode the file without any MIME headers. Next, in the opening <field> tag, insert the “filename” attribute in addition to the fid or name attribute like this: <field fid=”22” filename=”profilePhoto.jpg”>. The “filename” attribute value should be set to the name of the file WITHOUT any path, just as shown above. Then, between the <field fid=”myfid” filename=”myFile.whatever> tag and the end tag </field>, you insert the raw base64 encoded text from the encoded file. Date values should be passed in formatted as MM-DD-YYYY or as milliseconds since January 1st, 1970 00:00:00 GMT. Note that the QuickBase HTML API returns dates as milliseconds since January 1st, 1970 00:00:00 GMT which is the same internal representation used by JavaScript. Phone Number fields require the use of four characters “.xx.” to delimit a phone number from its extension. So the phone number 978-5551122 x123 would be passed in as 978-5551122.xx.123 to API_AddRecord. For fields of type user, supply the user’s email address or the userid.

Parameter

Value

Required?

disprec

Specify <disprec /> if you want to display the edited record within the QuickBase application. There may be an application login required before the record can be displayed.

If present, return data is the normal QuickBase HTML page that displays the record. fform

Specify <fform /> if you are invoking this from within an HTML form that has checkboxes and you want those checkboxes to set QuickBase checkbox fields.

ignoreError

Specify a value of 1 for this parameter to suppress the error that is returned when a builtin field (for example, Record ID#) is written-to in an API_AddRecord call.

If this is not specified, by default, an error is returned in the above scenario. ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

rid

Record ID of the record that was edited

num_fields_changed

The number of record fields successfully updated in the edit.

update_id

Example XML Request POST https://www.quickbase.com/db/6mpjiez8? Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_EditRecord <qdbapi> <rid>17</rid> <update_id>1205700275470</update_id> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <udata>mydata</udata> <field name="email">cucamonga@chuck.com</field> <field name="phone">650-345-8768.3456</field> </qdbapi>

Example Response <?xml version="1.0" ?> <qdbapi> <action>API_EditRecord</action> <errcode>0</errcode> <errtext>No error</errtext> <ticket>2_bddqkpam2_dpsx_b_dhfjng8kqhysrb2vbisibpzjqz7</ticket> <rid>17</rid> <num_fields_changed>2</num_fields_changed> <update_id>1205700275470</update_id> </qdbapi>

Cl ick to Add or See Comments

API_FieldAddChoices Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_FieldAddChoices <qdbapi> <udata>mydata</udata> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <fid>11</fid> <choice>Don Tomas</choice> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6qj8mryz?act=API_FieldAddChoices&fid=7&choice=Bob&choice=Harry&choice=Mary& ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25

Usage If you have administrative rights, you can add new choices through this call whenever you want. If you donâ&#x20AC;&#x2122;t have these rights, you can only invoke this call if the multiple-choice field properties are set to allow new choices to be added. (In the UI, in the Field Properties pages available to administrators, you do this by checking the checkbox labeled Allow users to create new choices--or use API_SetProperties to do the same thing.) Typically, but not always, you would have default values set up in a multiple choice field. For example, sales rep or support rep names. In some scenarios, you might need to add choices to these multiple choice fields. If the choice you add already exists in the multiple choice list, the choice will not be added to the list (no duplicates) to the list.

Request Parameters Parameter

Value

Mandatory?

fid

The field ID of the multiple choice field you are adding choices to.

yes

choice

You can add one or more choices, with one choice per <choice></choice> tag.

yes

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

fid

The field ID of the multiple choice field to which you added choices.

fname

The label of the field to which you added choices.

numadded

The number of choices successfully added.

Sample XML Request <qdbapi> <udata>mydata</udata> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <fid>11</fid> <choice>Don Tomas</choice> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_FieldAddChoices</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <fid>11</fid> <fname>Fumables</fname> <numadded>1</numadded> </qdbapi>

Cl ick to Add or See Comments

API_FieldRemoveChoices Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_FieldRemoveChoices <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <fid>11</fid> <choice>Black</choice> <choice>Blue</choice> <qdbapi>

URL Alternative https://www.quickbase.com/db/ 6qj8mryz?act=API_FieldRemoveChoices&fid=7&choice=Bob&choice=Harry&choice=Ma ry&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25

Usage You call this to remove one or more of the options listed within a multiple-choice field. If you created those choices, you can remove them with this call. To remove choices you did not create you must have administrator rights.

Request Parameters Parameter

Value

Mandatory?

fid

The field ID of the multiple choice field you are removing the choices from.

yes

choice

You can remove one or more choices, with one choice per <choice></choice> tag.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

fid

The field ID of the multiple choice field from which you removed choices.

fname

The label of the field from which you removed choices.

numremoved

The number of choices successfully removed. Notice that you can have a partial success here. Some of the choices might be removed and some might not be removed, but the call will be considered successful if one or more can be removed. You should check the value here to make sure it is what you expect.

Sample XML Request <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <fid>11</fid> <choice>Black</choice> <choice>Blue</choice> <qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_fieldremovechoices</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydatamin</udata> <fid>11</fid> <fname>Color Choices</fname> <numremoved>2</numremoved> </qdbapi>

API_FindDBByName Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_FindDBByName <qdbapi> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <dbname>TestApp</dbname> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_FindDBByName&dbname=TestApp&ticket=2_bdh78chd4_dpsx_b_dnb ypa8d372j5rb6vt6kfdx7ty25

Usage You use this call to get the application-level dbid of an application whose name you know, Only those applications that granted you access rights will be searched. Because you can have multiple applications with the same name, you should be aware that more than one application dbid can be returned.

Request Parameters Parameter

Value

Mandatory?

dbname

The name of the application whose dbid you want.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

dbid

You will get one application dbid for each application whose name matches the one you specified in the request.

dbname

The application name, echoed in the response.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_FindDBByName</action> <errcode>0</errcode> <errtext>No error</errtext> <dbid>bdcagynhs</dbid> <dbid>bddrqepes</dbid> <dbname>TestTable</dbname> </qdbapi>

Cl ick to Add or See Comments

API_GenAddRecordForm Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GenAddRecordForm <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <field name='email'>bada@bing.com</field> <field name='text'>Four score and seven years</field> <field name='multichoice_text'>Tom</field> </qdbapi>

Usage This call returns the standard QuickBase new record add page (HTML) for the table whose dbid you specify. It contains edit fields for the user to fill and a save button to add the record to the database. If you want to prefill any fields you can do so by supplying one or more field/value pairs in the request. Any fields not prefilled or filled in by the user will get the default values set in the table field properties.

Request Parameters Parameter

Value

Mandatory?

field

Specify the field name or fid of the field to be prefilled in the form and the value to be prefilled. For example, <field name=â&#x20AC;?bobsâ&#x20AC;?>Your Uncle</field.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Returns an HTML page containing the record add page with any prefilled values.

Cl ick to Add or See Comments

API_GenResultsTable Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GenResultsTable <qdbapi> <ticket>2_bdd6zutr5_dpsx_b_2wydyzcz5v287ccdfzdwfcsmj4</ticket> <query>{'11'.CT.'Bob'}AND{'19'.GTE.'5'}</query> <clist>6.7.9.11.16</clist> <slist>11.6</slist> <fmt>structured</fmt> <options>num-4.sortorder-D</options> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6c5xatxy?act=API_GenResultsTable&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6 vt6kfdx7ty25&qid=5&jht=1query={'6'.CT.'done'}AND{'14'.CT.'USA'}&clist=7.8&s list=6&options=sortorder-A

Usage This call is typically used in its URL form embedded in an HTML page, as described in “Embedding a QuickBase View into a Web Page”. When the HTML page is opened in a browser, the call runs automatically and returns results to qdbWrite() for display in the HTML page. You can also use this call to do a variety of other things, such as returning results as a JavaScript array, getting a bunch of records in CSV format or alternatively as tab separated values. By default, API_GenResultsTable returns the same number of rows as would be returned in the UI. However, you can specify a different number of rows in your table by including num-n in your options parameter, where you replace n with the number of rows to return. If you want to split up a result set into several tables, you do this by calling API_GenResultsTable once for each table, using the skp option in the second to nth invocation to skip over the records already returned. Embedding a QuickBase View into a Web Page Use the following procedure to embed a QuickBase view into a Web page on your Web site:

1. In your QuickBase application, create the view that you want to embed. 2. In the HEAD section of your Web page, add the following <script> block: <script lang="javascript" src="https://www.quickbase.com/ db/my_dbid?a=API_GenResultsTable&qid=5&jht=1"l&ticket=myticket> </script> replacing my_dbid with the table ID you want and myticket with a valid ticket. (If you don’t supply a ticket, the QuickBase login form will be shown when the page is opened and the user will have to log in first.) You can also supply your own query here, replacing <qid>5</qid> with your own query. See “API_DoQuery” for information on building a query. 3. In the HEAD section of your Web page, add the following style information: <style> td.m { font-family:verdana; font-size:70%; } td.hd { font-family:verdana; font-size:70%; font-weight:bold; color:white;} </style> By changing the attributes of these CSS tags, you can modify the format of the resulting table. 4. In the area of the Web page where you want the HTML table to display, add the following JavaScript code: <script lang="javascript"> qdbWrite(); </script> A Sample Web Page HTML with an Embedded Table <html> <head> <script lang="javascript" src="https://www.quickbase.com/ db/5rh82jcq?a=API_GenResultsTable &ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25&qid=5&jht=1"> </script> <style> td.m { font-family:verdana; font-size:70%; } td.hd { font-family:verdana; font-size:70%; font-weight:bold; color:white;} </style> </head>

<body> <h1>Example</h1> <table cellpadding=5 bgcolor=lightgreen> <tr> <td valign=top nowrap><b>A QuickBase table<br>embedded in a<br>page of HTML </td> <td> <script lang="javascript"> qdbWrite(); </script> </td> </tr> </table> </body> </head> </html>

Request Parameters Parameter

Value

Mandatory?

query or qid or qname

If you use <query>, you must supply a query string. The query string you supply is in this form: <query>{myfid.operator.value}</query> See “API_DoQuery”for information on building your own query.

no (returns all records if absent)

You use <qid>n</qid>if you want to use a saved query and want to use its query ID. You use <qname>myQuery</qname> if you want to use a saved query and refer to it by its queryname. clist

A period delimited list of field IDs to be returned. The order you list these in is the order in which they’ll be returned.

no (returns the table’s default columns if absent)

slist

A period delimited list of field IDs for sorting.

jht

This parameter returns the HTML for a table as a JavaScript function named qdbWrite(). You can then embed the HTML table into a Web page by calling the JavaScript function in the area of the Web page where you want the table to display. Set the value of the parameter to ‘n’ if you want the new look and feel introduced on Apr-122003. Set the value of this parameter ‘1’ if you want the CSS styles that render the HTML table with the QuickBase look and feel prior to Apr-112003.

Parameter

Value

jsa

Include this parameter set to the value 1 (one) if you want the returned results as a JavaScript array.

options

A period-delimited list containing any or any combination of the following options:

Mandatory?

yes

num-n return a maximum of n records onlynew return only those records marked with new or updated flags skp-n skip the first n records returned by the query sortorder-A for ascending sorts sortorder-D for descending sorts ned to omit the edit icons in HTML table format nvw to omit the view icons in HTML table format nfg to omit the new and updated icons in HTML table format phd for plain (non-hyperlinked) headers abs for absolute URLs csv for comma-separated value output format tsv for tab-separated value output format ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values If you specify the jht option, the results are written to qbdWrite() embedded in the HTML page. Optionally, if you specify CSV or tab in the options parameter, the return will be comma separated values (CSV) or tab separated values, respectively. If you specified jsa, the javascript arrray is returned.

Cl ick to Add or See Comments

API_GetDBInfo Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetDBInfo <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetDBInfo&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kf dx7ty25

Usage You can invoke this on the application-level dbid or on a table dbid to get metadata information, such as the last time the table was modified. For example, you might use this function to find out if the table has changed since you last used it, or to find out if a new record has been added to the table.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

Element Name

Value

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

dbid

The table ID

dbname

The name of the application or table

lastRecModTime

The last time a user modified a record

lastModifiedTime

The last time a user modified the table

createdTime

The time the table was created

lastAccessTime

The last time a user accessed the table

numRecords

The number of records in the table

mgrID

A number that uniquely identifies the table manager

mgrName

The name of the table manager

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GetDBInfo</action> <errcode>0</errcode> <errtext>No error</errtext> <dbname>test</dbname> <lastRecModTime>1205806751959</lastRecModTime> <lastModifiedTime>1205877093679</lastModifiedTime> <createdTime>1204745351407</createdTime> <numRecords>3</numRecords> <mgrID>112149.bhsv</mgrID> <mgrName>AppBoss</mgrName> <version>1.42</version> </qdbapi>

Cl ick to Add or See Comments

API_GetDBPage Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetDBPage <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <pageID>3</pageID> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetDBPage&pageid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372 j5rb6vt6kfdx7ty25

Usage QuickBase allows you to store various types of pages, ranging from user-guide pages for your application to Exact Forms which are used to automate insertion of data into Word documents using a special Word template from QuickBase. This call lets you retrieve one of those pages in HTML.

Request Parameters Parameter

Value

Mandatory?

pageID

The ID of the page. Alternatively, you can use the pagename if you know that.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The requested page is returned in HTML.

Cl ick to Add or See Comments

API_GetDBvar Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetDBVar <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <varname>usercode</varname> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_DeleteRecord&rid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372 j5rb6vt6kfdx7ty25

Usage DBVars are variables you can create and set values in at the application level, using API_SetDBVar. (Use the application-level dbid.) This call lets you get the values from these DBVars. You can only get one DBVar per invocation. If you specify more than one varname, you’ll get only the first one. You’ll get an error if the DBVar you ask for does not exist.

Request Parameters Parameter

Value

Mandatory?

varname

You must specify a varname that exists in the target application.

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

value

The value of the DBVar.

Sample XML Request <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <varname>usercode</varname> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_getDBvar</action> <errcode>0</errcode> <errtext>No error</errtext> <value>12</value> </qdbapi>

Cl ick to Add or See Comments

API_GetNumRecords Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetNumRecords <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetNumRecords&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6v t6kfdx7ty25

Usage Returns the number of records in the table. You need to specify a table-level dbid.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

Element Name

Value

udata

Optional. Contains any udata value supplied in the request.

num_records

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GetNumRecords</action> <errcode>0</errcode> <errtext>No error</errtext> <num_records>17</num_records> </qdbapi>

Cl ick to Add or See Comments

API_GetOneTimeTicket Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetOneTimeTicket <qdbapi> <udata>mydata</udata> <ticket>2_bdd6zutr5_dpsx_b_2wydyzcz5v287ccdfzdwfcsmj4</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetOneTimeTicket&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5r b6vt6kfdx7ty25

Usage This call returns a one-use ticket (can be used one time only) that expires after 5 minutes along with a temporary user ID that is good only for that ticket. This call does not affect the validity of any ticket cookies returned from API_Authenticate.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

Element Name

Value

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

ticket

The one-time ticket.

userid

A temporary user ID good for only this ticket.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <qdbapi> <action>API_GetOneTimeTicket</action> <errcode>0</errcode> <errtext>No error</errtext> <ticket>2_bddg3vk49_bw8m32_b_rgwpgqd4dirkxdb29fc22zbw5d</ticket> <userid>55521080.cjub</userid> </qdbapi>

Cl ick to Add or See Comments

API_GetRecordAsHTML Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetRecordAsHTML <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <rid>2</rid> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetRecordAsHTML&rid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d 372j5rb6vt6kfdx7ty25

Usage You invoke this call on a table-level dbid to return a record within an HTML fragment that can be embedded in another Web page. Embedding a QuickBase View into a Web Page Use the following procedure to embed a QuickBase record into a Web page on your Web site: 1. In the HEAD section of your Web page, add the following <script> block: <script lang="javascript" src="https://www.quickbase.com/ db/dddddddd?a=API_GetRecordAsHTML&rid=n&jht=1"> </script> where dddddddd is the table ID and n is the record ID for the record that you want to embed. 2. In the HEAD section of your Web page, add the following style information: <style> td.m { font-family:verdana; font-size:70%; } td.hd { font-family:verdana; font-size:70%; font-weight:bold; color:white;} </style> 3. By changing the attributes of these CSS tags, you can modify the format of the resulting table. 4. 3. In the area of the Web page where you want the HTML table to display, add the following JavaScript code: API_GetRecordAsHTML 107 (c) 2008 Intuit Inc. All rights reserved.

5. <script lang="javascript"> 6. qdbWrite(); 7. </script> Example Web Page Code <html> <head> <script lang="javascript" src="https://www.quickbase.com/ db/5rh82jcq?a=API_GetRecordAsHTML&rid=5&jht=1"> </script> <style> td.m { font-family:verdana; font-size:70%; } td.hd { font-family:verdana; font-size:70%; font-weight:bold; color:white;} </style> </head> <body> <h1>Example</h1> <table cellpadding=5 bgcolor=lightgreen> <tr> <td valign=top nowrap><b>A QuickBase table<br>embedded in a<br>page of HTML</td> <td> <script lang="javascript"> qdbWrite(); </script> </td> </tr> </table> </body> </head> </html>

Request Parameters Parameter

Value

Mandatory?

rid

The record ID of the record to be returned. You can get the recordID of any record in a query. (See “API_DoQuery”)

yes

jht

The value of the parameter must be 1. ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The requested record in an HTML fragment. Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <rid>2</rid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GetRecordAsHTML</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_GetRecordInfo Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetRecordInfo <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <rid>2</rid> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetRecordInfo&rid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d37 2j5rb6vt6kfdx7ty25

Usage You invoke this call on a table-level dbid to get all of the fields in a record. You could use API_DoQuery to do the same thing, but this call is lots easier if you want all the fields.

Request Parameters Parameter

Value

Mandatory?

rid

The record ID of the record you want. You can get the recordID of any record in a query. (See “API_DoQuery”)

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

rid

The record ID, echoed back.

num_fields

The total number of fields in this record, including builtin fields.

update_id

The update ID, to be used in editing the field.

<field> aggregates

There will be several (num_field many) field aggregates returned. All record fields will be returned, even the standard built-in fields. The aggregate is structured as follows: <field> <fid>8</fid> <name>URL</name> <type>URL</type> <value>www.intuit.com</value> </field> Some fields may have additional elements.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <rid>20</rid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_getrecordinfo</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydatamin</udata> <rid>20</rid> <num_fields>28</num_fields> <update_id>1205780029699</update_id>

<field> <fid>6</fid> <name>user</name> <type>User</type> <value>Lodbrok</value> <printable>Boneless, Ivar</printable> </field> <field> <fid>7</fid> <name>file attachment</name> <type>File Attachment</type> <value>BatchID.html</value> </field> . . . </qbdapi>

Cl ick to Add or See Comments

API_GetRoleInfo Header and XML POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetRoleInfo <qdbapi> <ticket>1_6fy9bwi5_j22_dauzsw6b7mvehgdf5c9ajduh6fh5</ticket> </qdbapi>

Usage You invoke this call on the application-level dbid to get all of the roles that apply to the application. Each application can have its own set of roles that govern user access to that application. To find out what the roles are for an application, you can invoke this call to return all of the roles (name, ID, and application access level) available in the specified application. The access level returned in the <access> field is one of these available access types: •

Basic Access (able to view/add/modify records, depending on permissions)

•

Basic Access with Share (same as Basic, but can share with application with other users)

•

Administrator (full administrative access)

Request Parameters

Parameter

Value

Mandatory

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

roles

An aggregrate containing one or more roles, structured as follows: <roles> <role id="11"> <name>Participant</name> <access id="3">Basic Access</access> </role> </roles Each role returned has a role ID as an attribute and contains a role name and the application access level that is conferred by the role.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: 77 QUICKBASE-ACTION: API_GetRoleInfo <qdbapi> <ticket>2_bdcvdpy5y_dpsx_b_ddxjsb5bpjfwdydwa3qhqb89jfxc</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GetRoleInfo</action> <errcode>0</errcode> <errtext>No error</errtext> <roles> <role id="10"> <name>Viewer</name> <access id="3">Basic Access</access> </role>

<role id="11"> <name>Participant</name> <access id="3">Basic Access</access> </role> <role id="12"> <name>Administrator</name> <access id="1">Administrator</access> </role> </roles> </qdbapi>

Cl ick to Add or See Comments

API_GetSchema Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetSchema <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_GetSchema&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kf dx7ty25

Usage If you invoke this call on an application-level dbid, it returns metadata information about the application, such as any DBVars created for it and all child table dbids as well. If you invoke this call on a table dbid, the DBVars are also listed, but there will additionally be table-related information such as queries, field IDs (fid), and the current property settings for each field. Table-Schema Coolness: Saved Queries For You to Use Invoking this call against a table dbid gets you the standard default “List All” and “List Changes” queries. But more usefully, it also returns any custom queries (the UI calls these “reports”) that you have created in the UI and saved as a Shared Report. This is handy because you can most easily construct your queries in the QuickBase UI. Then, get their ID in the API_GetSchema call, and specify them by their query ID or query name in the various API calls that use queries, instead of laboring over the query string construction yourself. Here’s a sample of what one of these saved queries looks like in the response:

<query id="5"> <qyname>Complete Refuel</qyname> <qytype>table</qytype> <qydesc>fuel quantity greater than 10 gallons</qydesc> <qycrit>{&#039;7&#039;.AF.&#039;03-242008&#039;}AND{&#039;6&#039;.EX.&#039;10&#039;}</qycrit> <qyclst>8.6</qyclst> <qyopts>nos.</qyopts> <qycalst>0.0</qycalst> </query>

More Table-Schema Coolness: Field Help as Tooltips You can specify field help in the properties for each field, and if you do, API_GetSchema returns it. One useful way to use this feature is to load the field help into a tooltip.

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

table

the <table> aggregate contains all of the application metadata or field metadata, depending on the dbid supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample Application-level Response <?xml version="1.0" ?> <qdbapi> <action>API_GetSchema</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <table> <name>API created Sample</name> <desc>This is a sample application.</desc> <original> <table_id>bdb5rjd6h</table_id> <cre_date>1204586581894</cre_date> <mod_date>1206394201119</mod_date> <next_record_id>1</next_record_id> <next_field_id>7</next_field_id> <next_query_id>5</next_query_id> <def_sort_fid>6</def_sort_fid> <def_sort_order>1</def_sort_order> </original> <variables> <var name="Blue">14</var> <var name="Jack">14</var> <var name="Magenta">12</var> <var name="usercode">14</var> </variables> <chdbids> <chdbid name="_dbid_doug_s_api_created_sample">bdb5rjd6g</chdbid> <chdbid name="_dbid_vehicle">bddrydqhg</chdbid> </chdbids> <fields> </fields> </table> </qdbapi>

Sample Table-level Response <?xml version="1.0" ?> <qdbapi> <action>API_GetSchema</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <table> <name>API created Sample</name> <desc>This is a sample contact manager table.</desc> <original> <table_id>bdb5rjd6g</table_id> <cre_date>1204586581894</cre_date> <mod_date>1206394201119</mod_date> <next_record_id>22</next_record_id> <next_field_id>24</next_field_id> <next_query_id>5</next_query_id> <def_sort_fid>6</def_sort_fid> <def_sort_order>1</def_sort_order> API_GetSchema 119 (c) 2008 Intuit Inc. All rights reserved.

</original> <variables> <var name="Blue">14</var> <var name="Jack">14</var> <var name="Magenta">12</var> <var name="usercode">14</var> </variables> <queries> <query id="1"> <qyname>List All</qyname> <qytype>table</qytype> <qycalst>0.0</qycalst> </query> <query id="2"> <qyname>List Changes</qyname> <qytype>table</qytype> <qydesc>Sorted by Date Modified</qydesc> <qyslst>2</qyslst> <qyopts>so-D.onlynew.</qyopts> <qycalst>0.0</qycalst> </query> </queries> <fields> <field id="6" field_type="text" base_type="text"> <label>Additional Information</label> <fieldhelp>Supply additional data about the problem.</fieldhelp> <nowrap>0</nowrap> . . . </field> </fields> </table> </qdbapi>

Cl ick to Add or See Comments

API_GetUserInfo Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GetUserInfo <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <email>Ragnar-Lodbrok@paris.net</email> <udata>optional data</udata> </qdbapi>

URL Alternative https://www.quickbase.com/db/ main?act=API_GetUserInfo&username=RagnarL&password=naught&email=RagnarLodbrok.net

Usage You invoke this call on db\main (no dbid) to get the user name and userid associated with the specified email address (the email used for QuickBase login). This call is useful in the context of granting a user access rights to your application and then inviting that user to your application. This call is typically made to return the QuickBase user ID for a user whose email address you know, in preparation for subsequent calls to API_AddUserToRole (grant access rights) and API_SendInvitation, both of which require the user ID. The user email that you specify must be recognized in QuickBase or this call won’t work. (For users who aren’t registered QuickBase yet, use the alternative call API_ProvisionUser.) If you don’t supply the email parameter, the ticket will be used to determine the user, which means you’ll get your own user ID, name, and email. (“You” in this case being the one to whom the ticket was issued).

Request Parameters Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

The email address (as registered with QuickBase) of the user whose information you want.

If you don’t supply this parameter, the call returns the name, email, and userid of the user to whom the ticket was issued (you). udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

ticket

The ticket needed for application access.

user

The returned user aggregate. This aggregate always contains the user ID attribute and the user name. The user aggregate also contains the user login if the <email> parameter was NOT specified in the request. The aggregate is structured as follows: <user id="112149.bhsv"> <name>Ragnar Lodbrok</name> <login>Ragnar-Lodbrok@paris.net</login> </user>

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <email>Ragnar-Lodbrok@paris.net</email> </qdbapi>

<?xml version="1.0" ?> <qdbapi> <action>api_getuserinfo</action> <errcode>0</errcode> <errtext>No error</errtext> <user id="112149.bhsv"> <name>Ragnar Lodbrok</name> <login>Ragnar-Lodbrok@paris.net</login> </user> </qdbapi>

If <email> IS specified in the request: <?xml version="1.0" ?> <qdbapi> <action>api_getuserinfo</action> <errcode>0</errcode> <errtext>No error</errtext> <user id="112245.efy7"> <name>Ivar Boneless</name> </user> </qdbapi>

Cl ick to Add or See Comments

API_GetUserRole Header and XML POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: 77 QUICKBASE-ACTION: API_GetUserRole <qdbapi> <ticket>2_bdcvdpy5y_dpsx_b_ddxjsb5bpjfwdydwa3qhqb89jfxc</ticket> <userid>112245.efy7</userid> </qdbapi>

Usage You invoke this call on an application-level dbid to find out what roles are currently assigned to a specific user in an application. In contrast, the similar call API_UserRoles casts a bigger net, getting all users and their roles for the current application.

Request Parameters Parameter

Value

Mandatory?

userid

Supply the user ID of the user whose current role you want to retrieve. You can get the userid from API_Authenticate.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

Element Name

Value

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

user

The userid is returned as an attribute in this aggregate. The user aggregrate also contains the user name and role information for the user, structured as follows: <user id="112245.efy7"> <name>Ivar Boneless</name> <roles> <role id="10"> <name>Viewer</name> <access id="3">Basic Access</access> </role> </roles> </user> There will be one or more role. Each role returned has a role ID as an attribute and contains a role name and the application access level that is conferred by the role.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: 77 QUICKBASE-ACTION: API_GetUserRole <qdbapi> <ticket>2_bdcvdpy5y_dpsx_b_ddxjsb5bpjfwdydwa3qhqb89jfxc</ticket> <userid>112245.efy7</userid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GetUserRole</action> <errcode>0</errcode> <errtext>No error</errtext> <user id="112245.efy7"> <name>Ivar Boneless</name> <roles> <role id="10"> <name>Viewer</name> <access id="3">Basic Access</access> </role> </roles> </user> </qdbapi>

Cl ick to Add or See Comments

API_GrantedDBs Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GrantedDBs <qdbapi> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <udata>mydata</udata> <Excludeparents>1</Excludeparents> </qdbapi>

Usage You invoke this call on https://www.quickbase.com/db/main (no dbid) to get the names and dbids of all the applications and tables that you are entitled to access. If you specify both parent and child tables to be returned, you can easily identify the parent from child by the database name that is shown. In the returned names, child table names consist of the main application name followed by a colon and the child table name, as in the following example: Application name: MyApp Child table name: MyApp:MyTable

Request Parameters Parameter

Value

Mandatory?

Excludeparents

If you want the name and dbid of all eligible applications and child tables within them to be included in the return, set this to 1. (This is the default if this parameter is not included.)

If you want only the name and dbid of the eligible applications themselves, set this parameter to 0 (zero). adminOnly

Optional parameter, that if present will only return tables where the user making the request has administration privileges.

Parameter

Value

Mandatory?

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

databases

This aggregate contains the dbinfo sub-aggregate. There could be 0 (zero) or more dbinfo sub-aggregates returned in the response. The dbinfo is structured as follows: <dbinfo> <dbname>Comments</dbname> <dbid>bcaour4ak</dbid> </dbinfo> The returned dbinfos could be all applications only (no child tables) or all child tables only (no parent dbids), or a mixture of the two, depending on in request parameters.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_GrantedDBs <qdbapi> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <udata>mydata</udata> <Excludeparents>1</Excludeparents> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_GrantedDBs</action> <errcode>0</errcode> <errtext>No error</errtext> <databases> <dbinfo> <dbname>Misc_Comments</dbname> <dbid>bdadur4ak</dbid> <dbinfo> <dbname>Misc_Comments: Comment</dbname> <dbid>bdadur4am</dbid> </dbinfo> <dbinfo> <dbname>Misc_Comments: Rating</dbname> <dbid>bdbs8ms3g</dbid> </dbinfo> <dbinfo> <dbname>Misc_Comments: Emails</dbname> <dbid>bdbtbrxed</dbid> </dbinfo> <dbinfo> <dbname>API created Sample</dbname> <dbid>bdb5rjd6g</dbid> </dbinfo> </databases> <qdbapi>

Cl ick to Add or See Comments

API_ImportFromCSV Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_ImportFromCSV <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <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> URL alternative Because URLs can only be about one thousand characters in length this is not the recommended way to make this API call

Usage You invoke this call on a table-level dbid to add or update a batch of records. (In comparison, the API_AddRecord and API_EditRecord calls let you add or edit only one record at a time. There is one limitation, however: you canâ&#x20AC;&#x2122;t use this call to modify file attachment fields. The clist parameter is optional when adding new records to a table. However, when updating existing records, you must specify the clist parameter. QuickBase uses this parameter to determine whether new records are being added to a table or existing records are being updated. For an edit operation, the clist parameter must contain the field ID for the Record ID# field. Also, the CSV file must include a column that contains the record ID for each record that you are updating.

Request Parameters Parameter

Value

Mandatory?

records_csv

This is an aggregate containing the actual records you are importing <records_csv> <![CDATA[ your, record, values, go, here and, hopefully, here, as, well ]]> </records_csv>

yes

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

You don’t supply a clist if you are adding new records.

It depends

You must supply a clist if you are updating existing records. A period delimited list of field IDs to which the CSV columns map. 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. To prevent a column in the CSV file from being imported, enter a 0 in the field ID list. Examples In the following examples, the CSV file contains 4 columns. <clist>0.7.0.6</clist> In this example, QuickBase will not import either the first or third columns in the CSV file. <clist>7.8.5</clist> In this example, the field with a field ID of 7 is mapped to the first column in the CSV file, the field with a field ID of 8 is mapped to the second column, and the field with a field ID of 5 is mapped to the third column. Since the clist parameter does not include a fourth field ID, the fourth column in the CSV file is ignored. skipfirst

This parameter prevents QuickBase 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. To prevent the first line of data in a CSV file from being imported, the value of the skipfirst parameter must be 1.

Parameter

Value

Mandatory?

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

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.

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>1_65dpjetn_j26_b3wx956dnmqpwybwwni83bn7d65i</ticket> </qdbapi>

Sample XML Response (Added 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>

Sample XML Request (Update Existing Records) <qdbapi> <records_csv> <![CDATA[firstname,lastname,company,Record ID# john,Maryanchik,Custom Kitchens of Bayshore,7 bill,Johnson,Robert Carr Masonry,8 ]]></records_csv> <clist>7.8.6.3</clist> <skipfirst>1</skipfirst> <ticket>1_65drhbce_j26_dzqawxhdm4snjtbkrxvwzdekmqu2</ticket> </qdbapi>

Sample XML 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>

API_ProvisionUser Header and XML POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_ProvisionUser <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <roleid>11</roleid> <email>sanskor@sbcglobal.com</email> <fname>Margi</fname> <lname>Rita</lname> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bdb5rjd6h?act=API_ProvisionUser&email=DukeOHazard@sbcglobal.net&roleid=11&f name=Muggsy&lname=Boguesusername=PTBarnum&password=TopSecret

Usage This call is invoke on an application-level dbid for a user that is not yet registered with QuickBase, but whose email is known to you. This call •

Starts a new user registration in QuickBase using the supplied email, fname (first name), and lname (last name).

•

Gives application access to the user by adding the user to the specified role.

After you invoke this call, you’ll need to invoke API_SendInvitation to invite the new user via email. When the user clicks on the email invitation, the user is prompted to complete the brief registration. (At this time, the user can change the first and last name you assigned.) If a user already is registered with QuickBase, you can’t use this call: instead, to do these same tasks, you’ll have to use API_GetUserInfo, API_AddUserToRole, and API_SendInvitation.

Request Parameters Parameter

Value

Mandatory?

The email address of the person to whom you are granting access.

yes

roleid

Supply the role ID of the role you want to assign this user to. You can find this information by invoking API_GetRoleInfo.

yes

fname

The first name of the new QuickBase user.

yes

lname

The last name of the new QuickBase user.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

userid

The userid for the new user returned by QuickBase.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_ProvisionUser <qdbapi> <ticket>2_bdczwm66v_dpsx_b_dgatidydcbnenkb4u33d4b5exiq8</ticket> <roleid>11</roleid> <email>sanskor@sbcglobal.com</email> <fname>Margi</fname> <lname>Rita</lname> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_provisionuser</action> <errcode>0</errcode> <errtext>No error</errtext> <userid>112248.5nzg</userid> </qdbapi>

Cl ick to Add or See Comments

API_PurgeRecords Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_PurgeRecords <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <qid>10</qid> </qdbapi>

URL Alternative https://www.quickbase.com/db/ 6mpjiez8?act=API_PurgeRecords&qid=10&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372j 5rb6vt6kfdx7ty25

Usage Use this call carefully. If you do not supply a query parameter (query or qid or qname), ALL of the table records will be deleted! If you supply an empty query parameter (<query / >, or <qid /> or <qname />) all of the table records will be deleted as well. You invoke this call on the table-level dbid if you need to delete a bunch of records that meet your query criteria. (If you only need to delete one record, API_DeleteRecord would be a better choice.) All of the records meeting your query criteria will be deleted. For the query, you can construct your own query string, in which case you use the <query> element in the call.Alternatively you can use a saved query for the table, in which case you use <qid> or <qname>, whichever is handier for you. See “API_DoQuery” for information on saved queries or for instructions on building the query string.

Request Parameters Parameter

Value

Mandatory?

Use the <query> parameter if you want to supply a query string that you have constructed.

No, but unless you supply a non-empty query, all records in the table are deleted!

Use <qid> or <qname> if you want to use a standard default QuickBase query, or a custom shared query (report) created in the QuickBase UI. You can see all of the queries for a table by invoking API_GetSchema on the table. ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

num_records_deleted

The total number of records that were deleted.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <qid>10</qid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_PurgeRecords</action> <errcode>0</errcode> <errtext>No error</errtext> <num_records_deleted>21</num_records_deleted> </qdbapi>

Cl ick to Add or See Comments

API_RemoveUserFromRole Header and XML POST https://www.quickbase.com/db/bdb5rjd6h Content-Type: application/xml Content-Length: QUICKBASE-ACTION:API_RemoveUserFromRole <qdbapi> <udata>misc data</udata> <userid>112245.efy7</userid> <roleid>11</roleid> <ticket>1_6c6482m9_j36_c7mdvh9cmmtn9c8qtr5qchvw33v</ticket> </qdbapi> URL alternative https://www.quickbase.com/db/ 6mpjiez8?act=API_RemoveUserFromRole&userid=112245&roleid=11&username=Lester &password=Moore

Usage You invoke this call on an application-level dbid to remove the user entirely from the specified role in that application. Keep in mind that if the user has no other role, it eliminates the user entirely from the application’s role list. This means that calling API_UserRoles won’t return the user at all, which means you’ll need to get the user ID by calling API_GetUserInfo if you want to assign the user to another role in the future. This call can be used to remove the user entirely from any role in the application, effectively turning off access to that user. If you intend to turn off all access, you would need to call API_GetUserRole Info to see what roles the user has, then invoke API_RemoveUserFromRole on each role. If you expect to add that user to another role in the future, you should consider using API_ChangeUserRole, which can be used to turn off access (with a role set to None) while keeping the user on the application’s role list for future reinstatement or role change. If you are simply changing the user from one role to another, you should use API_ChangeUserRole.

Request Parameters Table 5-6

Request params

Parameter

Value

Required?

roleid

The ID of the role you want the user removed from.

yes

userid

The user you want removed from the role.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values The response to this call contains the following: Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Example XML Request <qdbapi> <udata>misc data</udata> <userid>112245.efy7</userid> <roleid>11</roleid> <ticket>1_6c6482m9_j36_c7mdvh9cmmtn9c8qtr5qchvw33v</ticket> </qdbapi>

Example Response <?xml version="1.0" ?> <qdbapi> <action>API_RemoveUserFromRole</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>misc data</udata> </qdbapi>

Cl ick to Add or See Comments

API_RenameApp Header and XML POST https://www.quickbase.com/db/bdb5rjd6h HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_RenameApp <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <newappname>Refueler</newappname> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bdb5rjd6h?act=API_RenameApp&newappname=Refueler&ticket=2_bdh78chd4_dpsx_b_d nbypa8d372j5rb6vt6kfdx7ty25

Usage You invoke this call on an application-level dbid to change the application name. No dbids, fids, or anything other than the application name is affected. You must have administrator rights to call this.

Request Parameters Parameter

Value

Mandatory?

newappname

The name you want your application to have.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <newappname>Refueler</newappname> </qdbapi>

Sample XML Response <<?xml version="1.0" ?> <qdbapi> <action>API_RenameApp</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> </qdbapi>

Cl ick to Add or See Comments

API_SendInvitation Header and XML POST https://www.quickbase.com/db/bdb5rjd6h HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_SendInvitation <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <userid>112249.ctdg</userid> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bdb5rjd6h?act=API_SendInvitation&userid=112249.ctdg&ticket=2_bdh78chd4_dpsx _b_dnbypa8d372j5rb6vt6kfdx7ty25

Usage You invoke this call to send an email invitation to your application. The userid is either from an existing QuickBase user that you have granted application access to via API_AddUserToRole, or from a new QuickBase user that you have created via API_ProvisionUser.

Request Parameters Parameter

Value

Mandatory?

userid

The ID of the QuickBase user you are inviting to your application.

yes

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bdde8sgnd_dpsx_b_ccuqipvcfdhuj7cfhsh9zd6r7v5t</ticket> <userid>112249.ctdg</userid> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_sendinvitation</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_SetDBvar Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_SetDBVar <qdbapi> <udata>mydata</udata> <ticket>2_bddh73kcp_dpvx_b_df76449xfsjqqcstv6qcb932bki</ticket> <varname>usercode</varname> <value>14</value> </qdbapi>

Usage If you have administrator rights in an application, you can invoke this to create a DBVar variable and/or set a value for it. If the DBVar already exists, this call will overwrite the existing value. You can only invoke this on one DBVar at a time. DBVars can only be set at the application level. So you must specify an application-level dbid.

Request Parameters Parameter

Value

Mandatory?

varname

The name you want the DBVar to have.

yes

value

The value you want to set in the DBVar

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

Element Name

Value

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> <varname>usercode</varname> <value>14</value> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_SetDBVar</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_SetFieldProperties Header and XML POST https://www.quickbase.com/db/bddfa5nbx HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_SetFieldProperties <qdbapi> <ticket>2_bdd6zutr5_dpsx_b_2wydyzcz5v287ccdfzdwfcsmj4</ticket> <udata>mydata</udata> <fid>6</fid> <label>Business Phone Number</label> <nowrap>0</nowrap> <bold>0</bold> <required>1</required> <appears_by_default>1</appears_by_default> <find_enabled>1</find_enabled> <allow_new_choices>0</allow_new_choices> <sort_as_given>0</sort_as_given> <carrychoices>0</carrychoices> <foreignkey>0</foreignkey> <unique>1</unique> <doesdatacopy>0</doesdatacopy> <fieldhelp>Contact phone number</fieldhelp> <num_lines>1</num_lines> <append_only>0</append_only> <allowHTML>1</allowHTML> <has_extension>1</has_extension> </qdbapi>

URL Alternative https://www.quickbase.com/db/ bddnc2idi?act=API_DeleteRecord&rid=18&ticket=2_bdh78chd4_dpsx_b_dnbypa8d372 j5rb6vt6kfdx7ty25

Usage You invoke this on a table-level dbid to set one or more properties of a field. Normally, you use this call after you create a new field using API_AddField, to set up its default behavior. However, you can also use this call at any time if you want to change properties, even if the affected field has data. You can get the fid value for a field and all of its available properties by using the API_GetSchema call.

Request Parameters Parameter

Value

Mandatory?

properties

Name/value pairs for the properties to be set

yes

fid

Field ID of the field to be changed

yes

ticket

The ticket needed for application access.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be â&#x20AC;&#x153;no errorâ&#x20AC;?. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

fid

The id of the field whose properties were successfully set.

fname

The label of the field whose properties were set.

Sample XML Request <qdbapi> <ticket>2_bddpwd9eh_dpsx_b_d5493fedi79b7uctweby2phdnys</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_SetFieldProperties</action> <errcode>0</errcode> <errtext>No error</errtext> <udata>mydata</udata> <fid>6</fid> <fname>Business Phone Number</fname> </qdbapi>

Cl ick to Add or See Comments

API_SignOut Header and XML POST https://www.quickbase.com/db/main HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_SignOut <qdbapi> </qdbapi>

URL Alternative https://www.quickbase.com/db/main?act=API_SignOut

Usage This call is used for those implementations that make use of the TICKET cookie rather than the <ticket> parameter. Invoking this call returns a null ticket cookie (with the name TICKET) that in some cases results in preventing applications at the local machine from accessing QuickBase applications until API_Authenticate is called for a new ticket cookie. However, this call does not invalidate any tickets, nor log off the caller from any QuickBase applications, nor prevent further access of QuickBase applications. If the caller has saved a valid ticket, the user can continue to use it.

Request Parameters Parameter

Value

Mandatory?

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: QUICKBASE-ACTION: API_Signout <qdbapi> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>api_signout</action> <errcode>0</errcode> <errtext>No error</errtext> </qdbapi>

Cl ick to Add or See Comments

API_UploadFile URL https://www.quickbase.com/db/ bddnc2idi?act=API_UploadFile&rid=18&uploadDataFileName=myfile.gif&ticket=2_ bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25

Usage This call is intended for use only by those environments (such as Flex or Flash) where the security architecture prevents you from accessing local files, in this case file attachments base64 encoded for upload into QuickBase. The process you need to do varies by your programming language-environment. If you use Flex, you will have to set the uploadDataFieldName argument of the upload method of the FileReference object to be _fid_fid where fid is the field id of the file attachment field (ex: _fid_13). You can also upload multiple files by setting the uploadDataFileName arg and using the FileReferenceList. Sample Response <?xml version="1.0" ?> <qdbapi> <action>API_UploadFile</action> <errcode>0</errcode> <errtext>No error</errtext> <file_fields> <field id="13">  <url>https://localhost/up/bc4gzy4nx/g/rc/ep/va/qchain.log</url> </field> </file_fields>| </qdbapi>

Cl ick to Add or See Comments

API_UserRoles Header and XML POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: 77 QUICKBASE-ACTION: API_UserRoles <qdbapi> <ticket>2_bdcvdpy5y_dpsx_b_ddxjsb5bpjfwdydwa3qhqb89jfxc</ticket> </qdbapi>

Usage You invoke this call to find out details about an application’s users and their roles. You have to use the application-level dbid; a table-level dbid returns an error. This call returns all users and their roles. (In contrast, the similar call API_GetUserRole gets only the user roles for the specified user.) You can call this if you have basic access rights or higher.

Request Parameters Parameter

Value

Mandatory?

ticket

Supply a valid ticket. You obtain a valid ticket from API_Authenticate. A ticket is also returned in the various API responses.

yes

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response. One possible use is to maintain state in the calling application.

Response Values Element Name

Value

action

Echoes the originating request, for example, API_AddField.

errcode

If successful, this will be 0. If there is a failure, there will be a code returned here. See Appendix A for a list of codes.

errtext

If successful, this will be “no error”. If there is a failure this contains more detail on the nature of the failure.

Element Name

Value

users

This aggregate contains one or more user subaggregates. Each of these user sub-aggregates contains the actual data about the user. The userid is returned as an attribute in the user subaggregate. The user sub-aggregrate also contains the user name and role information for the user, structured as follows: <users> <user id="112149.bhsv"> <name>Jack Danielsson</name> <roles> <role id="12"> <name>Administrator</name> <access id="1">Administrator</access> </role> </roles> </user> </users> Each role returned has a role ID as an attribute and contains a role name and the application access level that is conferred by the role.

udata

Optional. Contains any udata value supplied in the request.

Sample XML Request POST https://www.quickbase.com/db/57pa5vjf HTTP/1.0 Content-Type: application/xml Content-Length: 77 QUICKBASE-ACTION: API_UserRoles <qdbapi> <ticket>2_bdcvdpy5y_dpsx_b_ddxjsb5bpjfwdydwa3qhqb89jfxc</ticket> </qdbapi>

Sample XML Response <?xml version="1.0" ?> <qdbapi> <action>API_UserRoles</action> <errcode>0</errcode> <errtext>No error</errtext> <users> <user id="112149.bhsv"> <name>Jack Danielsson</name> <roles> <role id="12"> <name>Administrator</name> <access id="1">Administrator</access> </role> </roles> </user> <user id="112245.efy7">

<name>Ivar Boneless</name> <roles> <role id="10"> <name>Viewer</name> <access id="3">Basic Access</access> </role> </roles> </user> </users> </qdbapi>

Cl ick to Add or See Comments

APPENDIX A ERROR CODES

1 1

Code

Message

Possible Cause

No error

Unknown error

Invalid input

You did not specify a name for the new application. To grant Group Record permissions, you must specify the Target Group name. This option is available to corporate workgroup users only. You cannot place more than .5 MB in this field. You do not have permission to access this table. You did not specify the field name. The field identifier (fid) does not refer to an existing field. Please provide a valid field identifier.

Insufficient permissions

You do not have permission to perform the current operation. You do not have permission to clone an application. At a minimum, you must have View permission to clone an application. You do not have permission to query this table. At a minimum, you must have view permission to perform this operation. You do not have sufficient permission to delete the records you specified from this table.

bad ticket

No user account was found that matches the e-mail address (or screen name) and password you entered. Your ticket has expired or is invalid. By default tickets expire after eight hours of use. One-time use tickets expire after one use or after 5 minutes. Please try signing in again. To perform the current operation, you must supply one of the following: A user name and password A ticket To get a list of tables to which you have been granted access, you must supply one of the following: A user name and password A ticket

Unimplemented operation

Syntax error

Code

Message

Possible Cause

API not allowed on this application table

SSL required for this application table

Invalid choice

Could not parse XML input

Invalid source db id

Invalid account ID

Missing DBID or DBID of wrong type

Unknown username/password

No user account was found that matches the e-mail address (or screen name) and password you entered.

Unknown user

No user account was found that matches the e-mail address or screen name you entered.

You cannot set the specified field to "(choice)."

No group was found that matches the group name you entered. 22

Sign-in required

Feature not supported

No such record

There is no record in the table that matches the specified record identifier (rid).

No such field

There is no field in this table that matches the specified field identifier (fid).

No such query

There is no query in this table that matches the specified query identifier (quid). There is no query in this table that matches the specified query name (qname).

You cannot change the value of this field.

No data returned

Cloning Error

No such report

Periodic report contains a restricted field

Missing required field

The default value property for the specified field is blank. Please supply a non-blank value for this field. You have either provided a blank value for one or more required fields, or you haven't supplied any value for one or more required fields whose default property is blank.

attempting to add a nonunique value to a field marked "unique."

The following reguired fields are missing from your import data: <field_1> [[<field_2>]...]

Code

Message

Cached list of records not found

Update conflict detected

Account size limit exceeded

Database size limit exceeded

Your account has been suspended

You are not allowed to create applications

View too large

Too many criteria in query

Overflow

Item not found

Operation took too long

100

Technical Difficulties -- try again later

101

No such database

Possible Cause

The limit on the number of criteria is currently set to 100 and you have exceeded this limit

You do not have permission to access the specified table.

Cl ick to Add or See Comments