Stacked

Integration Guides

Best practices and patterns for integrating with Stacked's API.

Idempotency Keys

Prevent Duplicate Operations

Use idempotency keys to prevent duplicate operations

Include the X-Idempotency-Key header when creating applications to prevent duplicates from retries or race conditions.

curl -X POST https://api.growstacked.com/api/v1/applications \
  -H "X-API-Key: sk_..." \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Error Handling

How to Handle API Errors Gracefully

  • 400 Bad Request: Validation errors - check the details array
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Application does not belong to your tenant
  • 429 Too Many Requests: Rate limit exceeded - check Retry-After header

Rate Limits

Understanding API Rate Limits

  • Per API Key: 100 requests per minute
  • Per IP Address: 10 requests per minute
  • Rate limit headers are included in all responses:X-RateLimit-RemainingX-RateLimit-Reset

Field Mapping

Understanding apiName Field Mapping

How external API field names map to internal question IDs

Field names in API requests map to internal question IDs through explicit apiName values defined in your tenant's questionsConfig. This ensures deterministic, tenant-specific field naming with no inference or automatic conversion.

Mapping Priority

The API checks field names in this order:

  1. apiName from questionsConfig (e.g., requestAmount → REQUEST_AMOUNT)
  2. mappingConfig.mapTo (tenant-specific overrides)
  3. Direct questionId (UPPER_SNAKE_CASE format, e.g., REQUEST_AMOUNT)

Example Mappings

requestAmount→REQUEST_AMOUNT
businessName→BUSINESS_INFORMATION_NAME
timeInBusiness→TIME_IN_BUSINESS
monthlyGrossSales→MONTHLY_GROSS_SALES

Getting Your Field Names

Each tenant defines their own apiName values in their questionsConfig. Contact your account manager to obtain your tenant's available field names and their corresponding question IDs.

Special Fields

Some fields have special handling:

  • email, phone, firstName, lastName map to the SIGN_UP question
  • Range values can be provided as objects: {start: 12, end: 24}