Skip to main content

Rate Limits and Bulk Imports

The SSN API is a REST API for individual resource operations. It does not currently provide a bulk-create endpoint that accepts an array or import file.

Request limit​

The current limiter is configured for 100 requests per minute per observed request IP in each running API process. It is not a shared quota per OAuth client. Clients sharing an egress IP can share a bucket, and routing across instances affects enforcement. Treat this as a pacing limit, not a guaranteed throughput allowance. When it is exceeded, the API returns 429 Too Many Requests. See Errors and Business Rules for the response shape and retry guidance.

Importing 1000+ records​

Large imports are supported as controlled sequences of individual requests, not as a single bulk request.

For imports of 1000 or more sites, site visits, or messages:

  • send one resource per POST request
  • throttle below 100 requests per minute
  • persist a unique Idempotency-Key and body for each resource create
  • honor Retry-After on 429; use bounded backoff for temporary failures and retain the same create key/body
  • keep a local progress log so the import can resume without duplicating rows
  • inspect the problem type on 409: an in-progress idempotency-pending response can be retried with the same key/body; unresolved or stalled requests require SSN reconciliation, not a new key

At a chosen pace of 100 requests per minute, 1000 create requests take about 10 minutes before other requests, latency, retries, and upstream processing are included. This is a planning estimate, not a service guarantee. Plan longer windows for site-visit imports, because each site visit may also validate related site, project, item, and site asset values.

Use a conservative starting pace of 20 to 60 requests per minute for large imports. Increase only after sandbox testing confirms stable response times and low retry volume.

Do not burst hundreds of concurrent create requests. High concurrency can increase 429 responses and upstream Quickbase errors without improving total import reliability.

Idempotency​

Resource creates (POST /sites, /site-visits, and /messages) should include an Idempotency-Key. Retry an uncertain create only with its original key/body; do not change the key to bypass a pending or conflicting result. Completed replay is available for 24 hours after completion, subject to current resource access. Pending/unresolved claims remain blocked until reconciled. An expired completed key is not permanent duplicate protection.

Uploads and subscription writes do not have this replay protection. Follow operation-specific retry guidance, including reconciliation before repeating writes with uncertain outcomes.

Use a stable import-row identifier in the key, for example:

Idempotency-Key: import-2026-05-14-sites-row-000123

Use a different key for each distinct record.