Getting Started with Nue APIs
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 KeysAPI Keys
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:
curl -H "nue-api-key: YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
https://api.nue.io/metadata/objectsEnvironments
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:
curl -H "nue-api-key: YOUR_API_KEY_HERE" \
https://api.nue.io/metadata/objectsA 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 PaginationPagination 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
# 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/objectsPagination
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
# 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=500Pagination Response Structure
All paginated responses include a pagination object with metadata about the current page and total dataset:
{
"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
# Start with first page
GET /customers?page=1&limit=50
# Navigate to next page using pagination metadata
GET /customers?page=2&limit=50Large Dataset Handling
# 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": 1000Best 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
{
"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
{
"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!