Making your first API call

Overview

This guide makes a first call to the sandbox with cURL.

Prerequisites

• A ComplianceGrid account
• A sandbox API key (cg_sk_...) and a subscription to the HS Code Lookup API in the sandbox (see *Creating your first API key*)
• cURL or any HTTP client

Step 1: Call an endpoint

Send your key in the x-api-key header:

Step 2: Inspect the response

A 200 response carries success, data and meta. Sandbox responses are canned sample data: they do not depend on what you send, and an endpoint without a sample returns { "success": true, "sandbox": true, "data": {} }. Use the sandbox to test your integration, not to judge results.

Optional: use a Bearer token instead

You can exchange your key for a token (see *OAuth 2.0 token exchange*) and send Authorization: Bearer . Sandbox tokens last 24 hours; production tokens last 1 hour.

Troubleshooting

• 401 invalid_api_key: the key is malformed, unknown or revoked
• 401 authentication_required: no key or token was sent
• 403 environment_mismatch: a sandbox key on the production host, or the reverse
• 403 not_subscribed: subscribe to the API for this environment
• 429 rate_limit_exceeded: the sandbox allows 60 requests a minute; wait for Retry-After