Timecard Query API · Open Time Clock · Product Q3

6. JavaScript Integration Examples

The following code is intended for a server-side JavaScript environment with fetch support. It includes single-page retrieval, automatic pagination, and a usage example.

6.1 Retrieve a Single Page

const API_URL =
  'https://api1.opentimeclock.com/Q3OTC/api';

const PAGE_SIZE = 1000;
const MAX_OFFSET = 100000;

// Retrieve one page.
// Return { records, hasMore }. records is [] when no records
// are found; hasMore is true when more pages remain.
// Throw an exception for application errors.
async function getTimecards({
  companyId,
  apiKey,
  employeeFullName,
  startDate,
  endDate,
  offset = 0,
  time = true,
  hours = true,
  lunch = true,
  // break is a reserved word, so it cannot be used as a binding name.
  break: includeBreak = true,
  ptoPending = true,
  ptoApproved = true,
  ptoDenied = true
}) {
  if (typeof apiKey !== 'string' || apiKey.length === 0) {
    throw new Error('Missing API key');
  }

  // All seven flags are required. At least one must be true.
  const url = new URL(API_URL);

  url.search = new URLSearchParams({
    cmd: 'Q3/api/getTimecardsApi',
    companyId: String(companyId),
    apiKey,
    employeeFullName,
    startDate,
    endDate,
    time: String(time),
    hours: String(hours),
    lunch: String(lunch),
    break: String(includeBreak),
    ptoPending: String(ptoPending),
    ptoApproved: String(ptoApproved),
    ptoDenied: String(ptoDenied),
    offset: String(offset)
  }).toString();

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      Accept: 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const result = await response.json();

  if (
    !result ||
    typeof result !== 'object' ||
    Array.isArray(result)
  ) {
    throw new Error('Unexpected API response');
  }

  if (result.status === 'ERROR') {
    const error = new Error(
      result.message || 'API request failed'
    );
    error.code = result.errorCode;
    error.field = result.field;
    throw error;
  }

  if (
    result.status !== 'SUCCESS' ||
    !Array.isArray(result.data)
  ) {
    throw new Error('Unexpected API response');
  }

  return {
    records: result.data,
    hasMore: result.hasMore === true
  };
}

6.2 Automatic Pagination

// Retrieve all records for the query, starting at offset 0.
async function getAllTimecards(params) {
  const records = [];

  for (
    let offset = 0;
    offset <= MAX_OFFSET;
    offset += PAGE_SIZE
  ) {
    const { records: page, hasMore } = await getTimecards({
      ...params,
      offset
    });

    for (const record of page) {
      records.push(record);
    }

    // Stop when the API reports that no more pages remain.
    if (!hasMore) {
      return records;
    }
  }

  // hasMore is still true at the maximum offset, so more
  // records remain. Do not silently return incomplete results.
  throw new Error(
    'Pagination limit reached; completeness cannot be ' +
    'confirmed. Narrow the date range and query again.'
  );
}

6.3 Usage Example

Save the functions above and the following code in a single timecards.js file. Configure the OPENTIMECLOCK_API_KEY environment variable on the server before running the script. Replace the company ID, employee name, and dates with actual values.

async function main() {
  const records = await getAllTimecards({
    companyId: 123456,
    apiKey: process.env.OPENTIMECLOCK_API_KEY,
    employeeFullName: 'John Smith',
    time: true,
    hours: true,
    lunch: true,
    break: true,
    ptoPending: true,
    ptoApproved: true,
    ptoDenied: true,
    startDate: '2026-08-01',
    endDate: '2026-08-15'
  });

  console.log(`Retrieved ${records.length} records`);

  // Process the records here:
  // save to a database, generate a report, or export a file.
}

main().catch(error => {
  // Do not log the request URL, API key, or raw request object.
  console.error('Query failed:', error.message);
  process.exitCode = 1;
});

6.4 Pagination Flow

Start with offset = 0
        |
        v
Request one page
        |
        v
Check HTTP status and JSON status
        |
        +-- Error: throw an exception
        |
        +-- Success: append records
                      |
                      v
                  hasMore false?
                    |       (the last page may hold 0-1,000 records)
                    +-- Yes: return all collected records
                    |
                    +-- No: increase offset by 1,000
                              |
                              v
                      Exceeds maximum offset?
                        |
                        +-- No: request the next page
                        |
                        +-- Yes: require a narrower date range

These examples focus on the core retrieval logic. They do not include request timeouts, retries, rate-limit handling, persistence, or resumable retrieval. Add these features as required by your production environment.