Toolcarton Getting Started: Quickstart Guide (2026)

Getting started overview

To begin using Toolcarton for generating synthetic data or mocking API responses, the initial steps involve setting up an account, obtaining API credentials, and making a foundational API call. Toolcarton offers a web-based user interface for defining data models and a REST API for programmatic interaction. This guide outlines the process, from account creation to your first successful data generation request, leveraging the official Toolcarton documentation for specific details.

The typical workflow for new users:

1. Account Creation: Register for a Toolcarton account. A free tier is available for initial exploration.
2. API Key Generation: Locate and securely store your API key from the Toolcarton dashboard. This key authenticates all programmatic requests.
3. Data Model Definition: Use the Toolcarton web UI to define the structure and data types for the synthetic data you wish to generate. This step is crucial before making API requests, as the API will reference these defined models.
4. First API Request: Construct and execute a basic API call to generate data based on one of your defined models. This confirms your setup is correct.

This page focuses on programmatic access via the REST API, which enables integration into automated testing pipelines, CI/CD workflows, or application development environments. For more detailed information on specific API endpoints and parameters, refer to the Toolcarton API Reference.

Create an account and get keys

Accessing Toolcarton's API requires an active account and a valid API key. Follow these steps to set up your environment:

1. Sign Up for a Toolcarton Account:

   • Navigate to the Toolcarton homepage.
   • Click on the "Sign Up" or "Get Started Free" button.
   • Provide the required information (email, password, etc.) to complete the registration process. Toolcarton offers a free tier which includes up to 5 data models and 1000 data rows, suitable for initial testing.
   • Verify your email address if prompted.

2. Log In to Your Dashboard:

   • After successful registration, log in to your Toolcarton dashboard. This is where you will manage your data models and retrieve API credentials.

3. Locate and Secure Your API Key:

   • Within the dashboard, navigate to the "API Keys" or "Settings" section. The exact path may vary; consult the Toolcarton documentation for API keys for precise instructions.
   • Generate a new API key if one is not already available.
   • Important: Treat your API key as sensitive information. It grants access to your Toolcarton account and data models. Do not hardcode it directly into client-side code, commit it to public version control systems, or expose it in publicly accessible applications. Store it securely, for example, using environment variables or a secrets management service. For best practices on API key security, refer to general guidelines on securing API keys from Google Cloud.
   • Copy your API key. You will need it for all authenticated API requests.

Your first request

Before making your first API request, you must define a data model within the Toolcarton web UI. This model specifies the structure and types of data Toolcarton will generate. For example, you might create a model named "User" with fields like "id" (UUID), "name" (full name), "email" (email address), and "created_at" (date time).

Once you have at least one data model defined (e.g., "User"), you can proceed with making an API call to generate data.

The following example demonstrates how to make a simple request to generate 5 rows based on a data model named "User" using curl. Replace YOUR_API_KEY with your actual Toolcarton API key and YOUR_MODEL_ID with the ID of your defined data model.

curl -X POST \
  https://api.toolcarton.com/v1/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "modelId": "YOUR_MODEL_ID",
    "count": 5
  }'

Example in JavaScript (Node.js with fetch)

This JavaScript example uses the fetch API, common in modern Node.js environments. Ensure you have Node.js installed to run this script. You might need to install a polyfill like node-fetch if using an older Node.js version, or simply run this within a browser environment (though API keys should not be exposed client-side).

const API_KEY = 'YOUR_API_KEY';
const MODEL_ID = 'YOUR_MODEL_ID'; // Replace with the actual ID of your data model

async function generateUserData() {
  try {
    const response = await fetch('https://api.toolcarton.com/v1/generate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        modelId: MODEL_ID,
        count: 5 // Request 5 data rows
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${errorData.message || 'Unknown error'}`);
    }

    const data = await response.json();
    console.log('Generated Data:', data);
    return data;
  } catch (error) {
    console.error('Error generating data:', error);
  }
}

generateUserData();

Example in Python

This Python example uses the widely adopted requests library. If you don't have it installed, run pip install requests.

import requests
import json

API_KEY = 'YOUR_API_KEY'
MODEL_ID = 'YOUR_MODEL_ID' # Replace with the actual ID of your data model

def generate_user_data():
    url = 'https://api.toolcarton.com/v1/generate'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}'
    }
    payload = {
        'modelId': MODEL_ID,
        'count': 5  # Request 5 data rows
    }

    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)
        data = response.json()
        print("Generated Data:", data)
        return data
    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err} - {response.text}")
    except Exception as err:
        print(f"Other error occurred: {err}")

if __name__ == "__main__":
    generate_user_data()

Upon a successful request, the API will return a JSON array containing the generated data rows, formatted according to your defined "User" data model.

Common next steps

After successfully generating your first set of synthetic data, you can expand your use of Toolcarton with these common next steps:

• Refine Data Models:

  • Iterate on your existing data models in the Toolcarton UI. Add more fields, apply specific data types and constraints (e.g., regex patterns, unique values), and create relationships between models to generate more complex and interdependent datasets.
  • Explore Toolcarton's various data types, such as realistic names, addresses, financial data, or custom regex-based patterns to match specific formats required by your application.

• Integrate into Testing Workflows:

  • Incorporate Toolcarton API calls into your automated testing frameworks (e.g., Jest, Pytest, JUnit). This allows you to generate fresh, realistic test data for each test run, improving coverage and reducing reliance on static test fixtures.
  • Consider using Toolcarton to populate databases (database seeding) in development or QA environments before running integration tests.

• Explore Advanced API Features:

  • Review the Toolcarton API Reference for advanced features, such as specifying locale, controlling data uniqueness, or generating data from multiple models in a single request.
  • Investigate options for mocking API responses directly, allowing your development environment to simulate external service behaviors without actual external calls.

• Monitor Usage and Upgrade Plan:

  • Keep track of your data generation usage within your Toolcarton dashboard.
  • If your needs exceed the free tier limits (5 data models, 1000 data rows), consider upgrading to a paid plan. Paid plans start at $29/month and offer increased capacities tailored for growing development and QA teams.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps and common problems:

1. Check API Key Validity:

   • Ensure YOUR_API_KEY is correctly copied from your Toolcarton dashboard and is included in the Authorization: Bearer header. An invalid or missing key will result in a 401 Unauthorized error.
   • Verify there are no extra spaces or characters around the key.

2. Verify Model ID:

   • Confirm that YOUR_MODEL_ID matches an existing data model ID in your Toolcarton account. You can find this ID in the Toolcarton web UI when viewing your data models. A non-existent model ID will typically lead to a 404 Not Found or 400 Bad Request error, indicating the API cannot locate the specified model.

3. Content-Type Header:

   • Ensure the Content-Type: application/json header is correctly set in your request. This tells the API to expect a JSON payload.

4. Request Body Format:

   • Double-check that your JSON request body is valid and correctly formatted. Missing commas, unclosed braces, or incorrect key names (e.g., model_id instead of modelId) will result in a 400 Bad Request error.
   • The MDN Web Docs on HTTP status codes provide a general reference for understanding common error responses.

5. Network Connectivity:

   • Confirm your machine has an active internet connection and is not blocked by a firewall from accessing https://api.toolcarton.com.

6. Consult Toolcarton Documentation:

   • The Toolcarton documentation on API errors provides specific error codes and messages that can help diagnose issues.
   • If you are still experiencing issues, consider reaching out to Toolcarton support with your request details and any error messages received.

Quick Reference: Getting Started with Toolcarton