Sandbox API reference

What does the sandbox group add to a test key?

Control. Test keys already send to the sandbox: no carrier, no cost, and the outcome follows from the destination number. The four operations here let a test choose the outcome, receive a fax it did not have to send, and start again from clean data.

The rest of the API is the same in the sandbox. Documents, quotes, faxes, webhooks and the wallet behave as they do live, with test credit in place of money.

How do I choose the outcome of a send?

POST /v1/sandbox/scenarios takes a scenario and, when you want one, a destination. With a destination the fixture applies to sends to that number. Without one it applies to every send of the organization that has no more specific fixture. The answer has the fixture's id and expires_at.

GET /v1/sandbox/scenarios returns the catalog: the scenario names, the scripted destinations and the fixtures that are active now. The names cover every way a fax can end, including the two a test rarely meets by chance, partial and unknown. The sandbox guide has the table of numbers and what each one does.

How do I rehearse receiving?

POST /v1/sandbox/inbound-faxes creates a synthetic inbound fax. The body takes to, and optionally from, pages and partial_content, which rehearses a cut-off transmission. The summary says the fax goes through the same pipeline as a real one. A private document is stored, an inbox item appears, and a fax.received event fires with its download reference.

A receiver built against this call is finished before the organization owns a number. The item is read through the inbox group like any other.

What does a reset remove?

DELETE /v1/sandbox/data resets the organization's test data. The answer has deleted, which counts what was removed, and wallet_available_micro, the test wallet after the reset. Live data is not touched: the call works on the test environment only.

Run it between test suites, so that one run's faxes and fixtures do not leak into the next.

Which credential do sandbox calls take?

A test key with sandbox:write, which the default API key carries. The four operations all name that scope, the catalog read included. A live key is refused with 403 sandbox_only. A signed-in session reaches the sandbox when it sends X-FFA-Environment: test, which is also the default for a session.

What does the sandbox not simulate?

A real fax line. A scripted outcome arrives at once or on the worker's schedule, not after a real call. Timing measured against the sandbox says nothing about a carrier. What the sandbox proves is your handling of each state, and of the events and holds that go with it.

How do sandbox events reach a webhook?

The same way live ones do. A test send fires fax.queued, fax.started and its ending event, with the same signature scheme as a live delivery. Register the receiver in the webhooks group with the test key, and it gets the events of test faxes only.

curl https://api.faxforagents.com/v1/sandbox/data \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/sandbox/inbound-faxes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"+15550000001"}'

curl https://api.faxforagents.com/v1/sandbox/scenarios \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/sandbox/scenarios \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"scenario":"delivered"}'