Cross-recognition for Health and Safety pre-qualification in the NZ construction industry

Totika API Documentations

The Tōtika Certified Contract API allows integration of Tōtika data in Airtable with external systems, following REST semantics and using JSON. It supports listing bases, tables, fields, and views, with a rate limit of 5 requests per second per base. Authentication is token-based, requiring HTTPS. The API includes fields like MemberStack ID, Business Name, and Certification Expiration Date. It supports filtering, sorting, and pagination. Errors follow HTTP status codes, with specific codes for user and server errors. Official and community-built API clients are available for various programming languages.

Full API Documentations: https://airtable.com/developers/web/api/introduction

Introduction

The Tōtika Certified Contract API API provides an easy way to integrate your Tōtika Certified Contract API data in Airtable with any external system. The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes.

The API documentation below is specifically generated for your base. We recommend that you use the graphical Airtable interface to add a few records of example data for each table. These records will be displayed in the documentation examples generated below.

To view documentation for all available endpoints, as well as documentation that has not been generated specific to your base, please visit here .

The ID of this base is appRex7PkE105dErb .

‍ Please note : if you make changes to a field (column) name or type, the API interface for those fields will change correspondingly. Therefore, please make sure to update your API implementation accordingly whenever you make changes to your Airtable schema from the graphical interface.

Official API client:

Community-built API clients:

Meta Data

This API gives you the ability to list all of your bases, tables, fields, and views. For more, see the metadata API documentation .

Rate Limits

The API is limited to 5 requests per second per base. If you exceed this rate, you will receive a 429 status code and will need to wait 30 seconds before subsequent requests will succeed.

The official JavaScript client has built-in retry logic.

If you anticipate a higher read volume, we recommend using a caching proxy. This rate limit is the same for all plans and increased limits are not currently available.

Authentication

Airtable uses simple token-based authentication. To learn more about other authentication methods like OAuth, please visit our developer documentation .

You can authenticate to the API by providing your secret API token in the HTTP authorization bearer token header.

All API requests must be authenticated and made over HTTPS.

Tōtika Certified Contractor Table

The id for Tōtika Certified Contractor is tble49rHJd96q4rlu . Table ids and table names can be used interchangeably in API requests. Using table ids means table name changes do not require modifications to your API request.

Fields

Each record in the Tōtika Certified Contractor table contains the following fields:

Field names and field ids can be used interchangeably. Using field ids means field name changes do not require modifications to your API request. We recommend using field ids over field names where possible, to reduce modifications to your API request if the user changes the field name later.

FIELD NAME
FIELD ID
TYPE
DESCRIPTION
EXAMPLE VALUES

MemberStack ID

fld8iET326wBcIrC7

Text

string
A single line of text.

61bb91db6b1e380004a679f7

Business Name

fldwMDkxsRMuA3ASq

Text

string
A single line of text.

COMPANY LIMITED

NZBN

fldeKblWpBAiRI5If

Text

string
A single line of text.

9429042230694

Principle / Lead Contractor?

fld6nysoDtK3vDOnx

Text

string
A single line of text.

"No"
‍"Yes"

Contact Name

fld36L3vnCnUrfg6S

Text

string
A single line of text.

John Smith

Business Email

fldrNGXQ4GNSZjXZV

Email

string
A valid email address.

[email protected]

Phone

fldvuOv72s1EfQiz1

Text

string
A single line of text.

+64 21 000 000

Contractor Type

fld7CTqK9sVWbwDSb

Single select

string
Selected option name.

[
"Civil contractor",
"Commercial builder",
"Residential builder",
"Specialist trade contractor",
"Professional Services / Consultant",
"Other (specify)",
"Suppliers",
"contractor",
"Professional services / Consultant"
]

Contractor Category

fldfoP0qb2HxOYc8Z

Single select

string
Selected option name.

[
"CAT 1",
"CAT 2",
"CAT 3",
"CAT S",
]

Scoring

fldN9F4My6j2UKFLh

Percent

number
Decimal number representing a percentage value. For example, the underlying cell value for 12.3% is 0.123. This field only allows positive numbers.

0.75

Service Locations

fld1uocOxjQ3l1wcG

Single select

string
Selected option name.

[
"Northland",
"Auckland",
"Waikato",
"Bay of Plenty",
"Gisborne",
"Hawke's Bay",
"Taranaki",
"Manawatū - Whanganui",
"Wellington",
"Tasman",
"Nelson",
"Marlborough",
"West Coast",
"Canterbury",
"Otago",
"Southland",
"All of NZ"
]

Certification Expiration Date

fldldVcCXGctRtM0t

Date

string (ISO 8601 formatted date)
UTC date, e.g. "2014-09-05".Synced - cannot be used with Update records API

2026-07-02

Contractor Status

fldZN26KiLTs3Udd4

Checkbox

boolean
This field is "true" when checked and otherwise empty.

true

Last Modified

fldlsQz2dzm44Oxqo

Date and time

string (ISO 8601 formatted date)
UTC date and time, e.g. "2014-09-05T07:00:00.000Z".

2024-07-02T04:01:34.000Z

Retrieving Tōtika Certified Contractor records

List Tōtika Certified Contractor records
Code

To list records in Tōtika Certified Contractor , issue a GET request to the Tōtika Certified Contractor endpoint. Note that table names and table ids can be used interchangeably. Using table ids means table name changes do not require modifications to your API request.

Returned records do not include any fields with "empty" values, e.g. "" , [] , or false .

You can filter, sort, and format the results with the following query parameters. Note that these parameters need to be URL encoded. You can use our API URL encoder tool to help with this. If you are using a helper library like Airtable.js, these parameters will be automatically encoded.

Note: Airtable's API only accepts request with a URL shorter than 16,000 characters. Encoded formulas may cause your requests to exceed this limit. To fix this issue you can instead make a POST request to /v0/{baseId}/{tableIdOrName}/listRecords while passing the parameters within the body of the request instead of the query parameters. See our support article on this for more information.

fields array of string s optional
Only data for fields whose names are in this list will be included in the result. If you don't need every field, you can use this parameter to reduce the amount of data transferred.

For example, to only return data from MemberStack ID and Business Name , pass in:fields: ["MemberStack ID", "Business Name"]

You can also perform the same action with field ids (they can be found in the fields section):fields: ["fld8iET326wBcIrC7", "fldwMDkxsRMuA3ASq"]

‍ filterByFormula string optional
A formula used to filter records. The formula will be evaluated for each record, and if the result is not 0 , false , "" , NaN , [] , or #Error ! the record will be included in the response. We recommend testing your formula in the Formula field UI before using it in your API request.

If combined with the view parameter, only records in that view which satisfy the formula will be returned.

The formula must be encoded first before passing it as a value. You can use this tool to not only encode the formula but also create the entire url you need. For example, to only include records where MemberStack ID isn't empty, pass in NOT({MemberStack ID} = '') as a parameter like this:filterByFormula: "NOT({MemberStack ID} = '')"

Note: Airtable's API only accepts request with a URL shorter than 16,000 characters. Encoded formulas may cause your requests to exceed this limit. To fix this issue you can instead make a POST request to /v0/{baseId}/{tableIdOrName}/listRecords while passing the parameters within the body of the request instead of the query parameters. See our support article on this for more information.

maxRecords number optional
The maximum total number of records that will be returned in your requests. If this value is larger than pageSize (which is 100 by default), you may have to load multiple pages to reach this total. See the Pagination section below for more.

pageSize number optional
The number of records returned in each request. Must be less than or equal to 100. Default is 100. See the Pagination section below for more.

sort array of object s optional
A list of sort objects that specifies how the records will be ordered. Each sort object must have a field key specifying the name of the field to sort on, and an optional direction key that is either "asc" or "desc". The default direction is "asc".

The sort parameter overrides the sorting of the view specified in the view parameter. If neither the sort nor the view parameter is included, the order of records is arbitrary.

For example, to sort records by MemberStack ID in descending order, send these two query parameters:
sort%5B0%5D%5Bfield%5D=MemberStack%20ID sort%5B0%5D%5Bdirection%5D=desc
‍
For example, to sort records by MemberStack ID in descending order, pass in:[{field: "MemberStack ID", direction: "desc"}]

view string optional
The name or ID of a view in the Tōtika Certified Contractor table. If set, only the records in that view will be returned. The records will be sorted according to the order of the view unless the sort parameter is included, which overrides that order. Fields hidden in this view will be returned in the results. To only return a subset of fields, use the fields parameter.

cellFormat string optional
The format that should be used for cell values. Supported values are:

json : cells will be formatted as JSON, depending on the field type.

string : cells will be formatted as user-facing strings, regardless of the field type. The timeZone and userLocale parameters are required when using string as the cellFormat.

Note : You should not rely on the format of these strings, as it is subject to change.

The default is json.

timeZone string optional
The time zone that should be used to format dates when using string as the cellFormat. This parameter is required when using string as the cellFormat.

userLocale string optional
The user locale that should be used to format dates when using string as the cellFormat. This parameter is required when using string as the cellFormat.

returnFieldsByFieldId boolean optional
An optional boolean value that lets you return field objects where the key is the field id.

This defaults to false, which returns field objects where the key is the field name.

recordMetadata array of strings optional
An optional field that, if includes commentCount, adds a commentCount read only property on each record returned.

Pagination
‍ The server returns one page of records at a time. Each page will contain pageSize records, which is 100 by default.

To fetch the next page of records, call fetchNextPage.

Pagination will stop when you've reached the end of your table. If the maxRecords parameter is passed, pagination will stop once you've reached this maximum.

Iteration may timeout due to client inactivity or server restarts. In that case, the client will receive a 422 response with error message LIST_RECORDS_ITERATOR_NOT_AVAILABLE . It may then restart iteration from the beginning.

Javascipt Code
‍ var Airtable = require('airtable');
var base = new Airtable({apiKey: 'YOUR_SECRET_API_TOKEN'}).base('appRex7PkE105dErb');

base('Tōtika Certified Contractor').select({
// Selecting the first 3 records in Grid view:
maxRecords: 3,
view: "Grid view"
}).eachPage(function page(records, fetchNextPage) {
// This function (`page`) will get called for each page of records.

records.forEach(function(record) {
console.log('Retrieved', record.get('MemberStack ID'));
});

// To fetch the next page of records, call `fetchNextPage`.
// If there are more records, `page` will get called again.
// If there are no more records, `done` will get called.
fetchNextPage();
‍
}, function done(err) {
if (err) { console.error(err); return; }
});

‍ OUTPUT
‍ Retrieved 61bb91db6b1e380004a679f7
Retrieved 6296aa45bdc5940004bc93df
Retrieved 631669dbc8b69f00047efdb7

FETCH FIRST PAGE
// If you only want the first page of records, you can
// use `firstPage` instead of `eachPage`.

base('Tōtika Certified Contractor').select({
view: 'Grid view'
}).firstPage(function(err, records) {
if (err) { console.error(err); return; }
records.forEach(function(record) {
console.log('Retrieved', record.get('MemberStack ID'));
});
});

‍ FETCH ADDITIONAL RECORD METADATA
‍ // If you want to fetch the number of comments for each record,
// include the `recordMetadata` param.
base('Tōtika Certified Contractor').select({
recordMetadata: ['commentCount']
}).firstPage(function(err, records) {
if (err) { console.error(err); return; }
records.forEach(function(record) {
console.log('Retrieved a record with', record.commentCount, 'comments');
});
});

Erros

The Tōtika Certified Contract API API follows HTTP status code semantics. 2xx codes signify success, 4xx mostly represent user error, 5xx generally correspond to a server error. The error messages will return a JSON-encoded body that contains error and message fields. Those will provide specific error condition and human-readable message to identify what caused the error.

Success code
Label
Explanation

200

OK

Request completed successfully.

User error codes
Label
Explanation

400

Bad Request

The request encoding is invalid; the request can't be parsed as a valid JSON.

401

Unauthorized

Accessing a protected resource without authorization or with invalid credentials.

402

Payment Required

The account associated with the API key making requests hits a quota that can be increased by upgrading the Airtable account plan.

403

Forbidden

Accessing a protected resource with API credentials that don't have access to that resource.

404

Not Found

Route or resource is not found. This error is returned when the request hits an undefined route, or if the resource doesn't exist (e.g. has been deleted).

413

Request Entity Too Large

The request exceeded the maximum allowed payload size. You shouldn't encounter this under normal use.

422

Invalid Request

The request data is invalid. This includes most of the base-specific validations. You will receive a detailed error message and code pointing to the exact issue.

Server error codes
Label
Explanation

500

Internal Server Error

The server encountered an unexpected condition.

502

Bad Gateway

Airtable's servers are restarting or an unexpected outage is in progress. You should generally not receive this error, and requests are safe to retry.

503

Service Unavailable

The server could not process your request in time. The server could be temporarily unavailable, or it could have timed out processing your request. You should retry the request with backoffs.