> This page is for version V1 (default).
> For other versions, use one of these documentation indexes:
> - V1 (default): https://docs.ottimate.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ottimate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server.

# Sandbox Environment

> **Warning**
>
> **All development and testing MUST be performed in the Sandbox environment.** Production credentials are only issued after successful validation in Sandbox. Never test integrations directly in Production as this will affect live accounting data and workflows.

## Quick Reference

Use these URLs when developing your integration:

| Environment    | Dashboard                                                | API Base                              | Auth Server                                     |
| -------------- | -------------------------------------------------------- | ------------------------------------- | ----------------------------------------------- |
| **Sandbox**    | [sandbox.ottimate.com](https://sandbox.ottimate.com)     | `https://sandbox-api.ottimate.com/v1` | `https://sandbox-auth.ottimate.com/oauth/token` |
| **Production** | [dashboard.ottimate.com](https://dashboard.ottimate.com) | `https://api.ottimate.com/v1`         | `https://auth.ottimate.com/oauth/token`         |

> **Note**
>
> Always start with Sandbox URLs during development. Replace with Production URLs only after receiving production credentials.

---

## What is the Sandbox Environment?

The Sandbox environment is a complete, isolated replica of the Ottimate production system designed specifically for development, testing, and validation. It provides a safe space to build and test your integration without any risk to live accounting data or workflows.

### Why Use Sandbox?

* **Risk-Free Testing**: Test your integration without affecting real accounting data or business operations
* **Experiment Freely**: Try different approaches, test edge cases, and debug issues without consequences
* **Realistic Environment**: Access the same features, APIs, and workflows available in production
* **Error Testing**: Safely test error handling and failure scenarios
* **Validation Required**: Complete and validate your integration before accessing production

---

## Sandbox vs Production

### Data Isolation

The Sandbox environment is completely separate from Production:

* **Independent Data**: Sandbox data and settings do not sync with or affect Production
* **Different Identifiers**: The same entity will have different Ottimate-generated IDs in each environment
* **Separate Credentials**: Sandbox and Production use different API keys, Client IDs, and Client Secrets
* **Isolated Users**: User accounts and permissions are managed separately

### Feature Parity

The Sandbox environment replicates all core production features:

* All API endpoints and operations
* Authentication flows
* Invoice processing and extraction
* Approval workflows
* Vendor and dimension management
* Catalog functionality

---

## Getting Sandbox Access

### Credential Provisioning

Ottimate provisions Sandbox and Production credentials in **two separate stages** to ensure proper testing and validation:

**Stage 1: Sandbox Access**
During the Discovery and Development phases, your Ottimate Partner Manager will:

1. **Create and configure a mock client account** in the Sandbox environment with all necessary features enabled (this is required for the API to function)
2. Provide you with:
   * Sandbox API Key (X-API-Key header)
   * Sandbox Client ID and Client Secret (OAuth2 credentials)
   * Access details for your configured Sandbox organization
   * Invitation to dedicated Slack channel for support

> **Warning**
>
> The API will not work without a properly configured client account in Sandbox. Ensure your Partner Manager has completed the organization setup before attempting API calls.

**Stage 2: Production Access**
After successful validation in Sandbox:

* Production API Key
* Production Client ID and Client Secret
* Access to production organization(s)
* Go-live support and monitoring

This staged approach mitigates the risk of impacting high-stakes accounting tasks and ensures your integration is production-ready.

---

## Using the Sandbox Dashboard

You can log in to the [Sandbox Dashboard](https://sandbox.ottimate.com) to test your integration from an end-user perspective and verify how your API calls affect the system.

### Testing Invoice Upload

The Sandbox supports multiple methods for creating and uploading invoices:

* **API Upload**: Use `POST /v1/invoices/upload` to upload invoice files for extraction
* **API Creation**: Use `POST /v1/invoices` to create invoices programmatically with structured data
* **Desktop Upload**: Test InstantCapture desktop upload functionality
* **Manual Creation**: Create invoices manually from the Invoice tab to understand the user workflow

### Viewing API Results

After making API calls, log in to the Sandbox Dashboard to:

* Verify invoices were created correctly
* Check extraction results from uploaded files
* Test approval workflows
* Validate dimension assignments
* Confirm vendor associations
* Review export status

---

## Recommended Testing Workflow

Follow this workflow to ensure comprehensive testing in Sandbox:

#### Step 0: Client Account Setup (Prerequisite)

**IMPORTANT**: Before you can use the API, a mock client account must be onboarded and configured in the Sandbox environment.

**What's required:**

* Your Ottimate Partner Manager will create and configure a test organization in Sandbox
* All necessary features and modules will be enabled for your integration
* User accounts and permissions will be set up
* The organization structure (companies, locations) will be configured

**Why this matters:**
The Ottimate API will not function without a properly configured client account. All API requests are scoped to a specific organization, so this setup is mandatory before any testing can begin.

**Action needed:**
Contact your Ottimate Partner Manager to confirm your Sandbox organization has been created and configured with:

* Organization name and settings
* Enabled features (Instantcapture, Purchase Orders, Catalog Match, etc.)
* Company and location structure
* Initial user accounts

Once confirmed, you'll receive:

* Your Sandbox organization ID or account identifier
* Confirmation that your API credentials are linked to this organization

#### Step 1: Authenticate

After your Sandbox organization is configured, obtain your first access token using the Sandbox Auth URL and your credentials:

```bash
curl -X POST https://sandbox-auth.ottimate.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: your-sandbox-api-key" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_SANDBOX_CLIENT_ID" \
  -d "client_secret=YOUR_SANDBOX_CLIENT_SECRET"
```

#### Step 2: Test With Authentic Data

Use accounting entities from your ERP for testing in Sandbox:

* Create accounting vendors using `POST /v1/vendors`
* Set up accounting dimensions using `POST /v1/dimensions`
* Configure catalog entries if needed
* Verify data in Sandbox Dashboard

#### Step 3: Test Core Workflows

Test all integration scenarios based on your AP workflow:

* Invoice creation and upload
* Data synchronization (vendors, dimensions)
* Invoice updates and modifications
* Approval workflows
* Error handling and edge cases

#### Step 4: Validate Results

Verify outcomes in the Sandbox Dashboard:

* Check that invoices appear correctly
* Validate approval chains
* Confirm dimension assignments
* Review export status

#### Step 5: Test Error Scenarios

Intentionally test failure cases:

* Invalid authentication
* Malformed requests
* Missing required fields
* Duplicate data handling
* Rate limiting behavior

#### Step 6: Schedule Validation

Once testing is complete, work with your Ottimate Partner Manager to:

* Review test results
* Complete validation checklist
* Address any issues or concerns
* Receive approval for production access

---

## Best Practices

### During Development

* **Use Sandbox URLs Consistently**: Always point to `sandbox-api.ottimate.com` and `sandbox-auth.ottimate.com` during development
* **Test Thoroughly**: Don't rush to production—test all features and edge cases in Sandbox first
* **Use Realistic Test Data**: Create test data that mirrors real-world scenarios you'll encounter in production
* **Document Test Cases**: Keep track of what you've tested and the results
* **Test Error Handling**: Intentionally trigger errors to ensure your integration handles them gracefully

### Data Management

* **Never Use Real Data**: Do not use actual company information, real vendor data, or sensitive information in Sandbox
* **Create Meaningful Test Data**: Use descriptive names for test entities (e.g., "Test Vendor - Electronics", "Test Invoice - High Value")
* **Clean Up Regularly**: Keep your Sandbox organized by archiving or removing old test data
* **Coordinate with Team**: If multiple developers share the Sandbox, coordinate data creation to avoid conflicts

### Security

* **Keep Credentials Secure**: Treat Sandbox credentials with the same security as production
* **Use Environment Variables**: Never hardcode credentials in your source code
* **Rotate Credentials**: Request new credentials if they may have been compromised
* **Don't Share Credentials**: Each developer should have their own set of credentials when possible

---

## Transitioning to Production

### Validation Requirements

Before receiving production credentials, Ottimate will validate:

* **Authentication**: Proper OAuth2 flow implementation and token management
* **Core Functionality**: All planned API operations working correctly
* **Error Handling**: Appropriate handling of API errors and edge cases
* **Data Integrity**: Correct data formatting and validation
* **Integration Stability**: Consistent performance and reliability

### Production Access Process

1. **Complete Sandbox Testing**: Finish all development and testing in Sandbox
2. **Request Validation**: Contact your Ottimate Partner Manager to schedule validation
3. **Validation Session**: Demonstrate your integration and review test results
4. **Receive Production Credentials**: Upon approval, receive production API key and OAuth credentials
5. **Update Configuration**: Update your integration to use production URLs
6. **Monitor Go-Live**: Ottimate team monitors initial production usage for any issues

### Production Differences

When moving to production, be aware:

* **Different Credentials**: Use production API key, Client ID, and Client Secret
* **Different URLs**: Update all endpoints to use `api.ottimate.com` and `auth.ottimate.com`
* **Different IDs**: Entity IDs from Sandbox won't exist in production—data must be recreated or synchronized
* **Real Impact**: All operations affect live accounting data and workflows
* **Production Support**: Access to production support and monitoring

---

## Need Help?

### Sandbox Access & Organization Setup

To receive Sandbox credentials and ensure your mock client account is properly configured, reach out to your Ottimate Partner Manager or contact [peter.niu@ottimate.com](mailto:peter.niu@ottimate.com).

**Before you start testing, confirm:**

* Your Sandbox organization has been created and configured
* All required features are enabled for your integration
* Your API credentials are linked to the organization

### Technical Support

During development, use your dedicated Slack channel for real-time support from the Ottimate technical team.

### Next Steps

#### [Authentication Guide](/auth)

Learn how to authenticate with Sandbox

#### [API Reference](/api-reference)

Explore available endpoints