--- title: Getting Started with Nue APIs slug: api-docs.nue.io docTags: createdAt: 2026-02-13T04:24:46.730Z --- Welcome to Nue's comprehensive API platform! Our APIs provide powerful capabilities for managing business processes, from metadata and object management to complete self-service workflows and third-party integrations. This guide will help you get up and running quickly. ## Overview Nue offers several specialized APIs designed to work together seamlessly: - **๐Ÿ“Š Metadata API** - Manage business objects, fields, layouts, filters, and value sets - **๐Ÿ’ฐ System Administration API** - Manage Nue system configuration including system settings, the import and export of products and pricing, orders and subscriptions, and other transactions. - **๐Ÿงพ Billing and Collections API** - Process billing, invoices, credit memos, payments and other financial transactions - **๐Ÿ›’ Commerce API** - AWS-powered APIs for customer self-service portals, e-commerce experiences, and real-time pricing - **๐Ÿ”„ Revenue Lifecycle API** - External access to Salesforce operations for system integrations and back-office automation - **๐Ÿ”— Stripe Integration API** - Seamlessly sync data between Nue and Stripe - **โœ๏ธ e-Signature Integration API** - Send quotes and documents for electronic signature via DocuSign and track signature status Each API comes with detailed guides covering specific use cases and implementation patterns. ## Authentication & API Keys ### Getting Your API Key To access Nue APIs, you'll need an API key. Contact your Nue administrator or account manager to obtain your key. Each environment requires a separate API key for security. For detailed information on Nue API keys, please refer to [API Keys](docId\:s0Dr69bK1jR0uP9cimrGP) ### API Key Security Best Practices - **Never expose API keys** in client-side code or public repositories - **Store keys securely** using environment variables or secure configuration management - **Rotate keys regularly** as part of your security practices - **Use different keys** for different environments (development, staging, production) ### Authentication Method All Nue APIs use API key authentication via the `nue-api-key` header: ```bash curl -H "nue-api-key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ https://api.nue.io/metadata/objects ``` ## Environments Nue provides multiple environments to support your development lifecycle: | Environment | Base URL | Purpose | Use Case | | -------------- | ---------------------------- | ------------------------ | ---------------------------- | | **Production** | `https://api.nue.io` | Live production data | Customer-facing applications | | **Sandbox** | `https://api.sandbox.nue.io` | Safe testing environment | Development and testing | ### Environment Selection Choose your environment based on your current development phase: - **Development**: Use Sandbox for building and testing features - **Staging**: Use Sandbox for pre-production validation - **Production**: Use Production for live customer data ## Making Your First Request Start with a simple authentication test: ```bash curl -H "nue-api-key: YOUR_API_KEY_HERE" \ https://api.nue.io/metadata/objects ``` A successful response indicates your API key is valid and you're ready to proceed. ## Response Format & Error Handling ### Common HTTP Status Codes | Code | Meaning | Action | | ----- | ------------ | ------------------------------------------------- | | `200` | Success | Request completed successfully | | `400` | Bad Request | Check request format and required fields | | `401` | Unauthorized | Verify your API key is correct and active | | `403` | Forbidden | Check your permissions for this operation | | `404` | Not Found | Verify the resource exists and the URL is correct | | `409` | Conflict | Resource already exists or constraint violation | | `429` | Rate Limited | Reduce request frequency | | `500` | Server Error | Contact support if issue persists | ## Rate Limits & Performance ### Rate Limiting - Standard rate limits apply to all endpoints - Limits vary by endpoint and subscription level - Rate limit headers are included in responses - Contact support for rate limit increases ### Best Practices - **Implement exponential backoff** for retries - **Cache responses** when appropriate to reduce API calls - **Use pagination** for large data sets (see [Pagination](docId\:Luhhoa-WuaKZgRqoKjaXN) section below) - **Batch operations** when possible - **Monitor rate limit headers** to avoid hitting limits ### Async Operations Some operations (like bulk data imports) are asynchronous: - Returns a job ID immediately - Poll job status endpoints for completion - Retrieve results when job completes *** ```bash # Set API key as environment variable export NUE_API_KEY="your_api_key_here" curl -H "nue-api-key: $NUE_API_KEY" \ -H "Content-Type: application/json" \ https://api.nue.io/metadata/objects ``` ## Pagination Nue APIs provide comprehensive pagination support for endpoints that return large datasets. Pagination follows industry-standard patterns with consistent parameter names and response structures across all endpoints. ### Pagination Parameters All paginated endpoints support these query parameters: | Parameter | Type | Default | Maximum | Description | | --------- | ------- | ------- | ------- | ------------------------------ | | `page` | integer | 1 | N/A | Page number (1-based indexing) | | `limit` | integer | 100 | 500 | Number of records per page | ### Parameter Examples ```bash # Get first page with default limit (100 records) GET /customers?page=1 # Get second page with custom limit (50 records) GET /customers?page=2&limit=50 # Maximum records per page GET /customers?page=1&limit=500 ``` ### Pagination Response Structure All paginated responses include a `pagination` object with metadata about the current page and total dataset: ```json { "status": "SUCCESS", "data": [...], "warnings": [], "pagination": { "page": 1, // Current page number (1-based) "limit": 100, // Records per page "total": 1247, // Total number of records available "totalPages": 13, // Total number of pages "hasNext": true, // Whether there is a next page "hasPrevious": false // Whether there is a previous page } } ``` ### Pagination Fields | Field | Type | Description | | ------------- | ------- | ------------------------------------------- | | `page` | integer | Current page number (starts at 1) | | `limit` | integer | Number of records requested per page | | `total` | integer | Total count of records across all pages | | `totalPages` | integer | Total number of pages available | | `hasNext` | boolean | True if more pages exist after current page | | `hasPrevious` | boolean | True if pages exist before current page | ### Endpoints with Pagination Support The following endpoints support pagination: - **Customers**: `GET /customers` - **Orders**: `GET /orders` - **Invoices**: `GET /invoices` - **Credit Memos**: `GET /creditMemos` - **Assets**: `GET /assets` - **Subscriptions**: `GET /subscriptions` - **Contacts**: `GET /contacts` - **Entitlements**: `GET /entitlements` - **Transaction Hub**: `GET /customers/{customerId}/transactionHubData` ### Navigation Examples ### Forward Navigation ```bash # Start with first page GET /customers?page=1&limit=50 # Navigate to next page using pagination metadata GET /customers?page=2&limit=50 ``` ### Large Dataset Handling ```bash # For large datasets, use smaller page sizes for better performance GET /customers?page=1&limit=25 # Check pagination metadata to understand total scope # Response: "totalPages": 40, "total": 1000 ``` ### Best Practices - **Start Small**: Use smaller page sizes (25-100) for better initial load times - **Monitor Total Count**: Check `total` field to understand dataset size - **Use Navigation Flags**: Rely on `hasNext`/`hasPrevious` for navigation logic - **Handle Empty Results**: When `total` is 0, `data` will be an empty array - **Respect Limits**: Maximum page size is 500 records per request - **Cache Pagination Metadata**: Store pagination info to avoid recalculating navigation ### Error Handling ### Invalid Page Parameters ```json { "status": "FAILURE", "errorType": "INVALID_PARAMETER", "errorCode": "INVALID_PAGE_PARAMETER", "message": "Invalid page parameter: '0'. Page must be a positive integer starting from 1" } ``` ### Invalid Limit Parameters ```json { "status": "FAILURE", "errorType": "INVALID_PARAMETER", "errorCode": "INVALID_LIMIT_PARAMETER", "message": "Invalid limit parameter: '600'. Limit must be between 1 and 500" } ``` ### Performance Considerations - **Efficient Pagination**: Uses cursor-based pagination internally for optimal database performance - **Consistent Ordering**: Results are ordered by `lastModifiedDate desc` for consistent pagination - **Count Optimization**: Total counts are calculated efficiently using database aggregation - **Memory Management**: Large datasets are streamed rather than loaded entirely into memory ## Data Formats & Conventions ### JSON Standards - All request and response bodies use JSON - Field names use camelCase convention - Dates follow ISO 8601 format (`YYYY-MM-DDTHH:mm:ss.sssZ`) - Monetary values are decimal numbers ## Getting Help - **API Documentation**: Comprehensive reference for all endpoints - **Support Portal**: Submit tickets for technical issues Ready to build something amazing? Start with our guided tutorials for your specific use case!