Testing in the sandbox

The sandbox lets you build and test an integration against the Veridion APIs without spending credits. It answers on the same URLs as production with generated, fake data, so moving to production means changing the key, not the code.

How it works

1. You exchange your sandbox key's client ID and client secret for an access token, exactly as you would with a production key.
2. You call the usual base URL, https://data.veridion.com, with that token. Veridion recognizes the sandbox key and sends the request to the sandbox instead of the real APIs.
3. The sandbox answers in the same shape as the real API, with fake data, and marks every response with the X-Veridion-Sandbox: true header.

Sandbox and production

Calling the sandbox

Getting a sandbox key

A sandbox key is a client ID and client secret, like a production key. Your Veridion representative provides sandbox keys alongside your production credentials. If you manage your keys in your Veridion account, you can create sandbox keys yourself on the API keys page.

Generating a token

Use the sandbox key's client ID and secret with the OAuth 2.0 Client Credentials flow described in Authentication. The request is the same as for a production key:

curl -X POST https://auth.veridion.com/oauth2/token \
  -u "your_sandbox_client_id:your_sandbox_client_secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=api:use"

Making a request

Send the token in the Authorization header, as in production:

curl -i -X POST https://data.veridion.com/match/v6/companies \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": {
      "commercial_names": ["Acme Robotics"],
      "address_txt": "Berlin, Germany"
    }
  }'

The response carries the sandbox header and a fake company. Headers and body are trimmed:

HTTP/1.1 200 OK
X-Veridion-Sandbox: true
Content-Type: application/json; charset=utf-8

{
  "resolution": {
    "scenario": "inferred_resolution",
    "summary": "The input required interpretation, and the result was selected as the most likely match based on consistent signals."
  },
  "count": 1,
  "result": [
    {
      "match_details": {
        "confidence_score": 0.83,
        "matched_on": ["company_name"]
      },
      "veridion_id": "5OTBHGR573I4X5TF",
      "company_name": "Clavorin Materials",
      "registered_name": "Clavorin Materials Inc.",
      "jurisdiction": "US-DE",
      "year_founded": 1959
    }
  ]
}

Generated data

The same request returns the same company

The sandbox generates every response from the request itself. Send the same request again and you get the same response; change an input and you get a different company, just as stable. Any input works, so you don't need a list of test companies.

IDs work across every API

Sandbox IDs use the production format: 16 characters. A veridion_id from Match & Enrich or Search returns the same company from Firmographics, Location Intelligence, Corporate structure, ESG and Products & Services (coming soon), so you can test multi-step workflows end to end.

curl https://data.veridion.com/corporate-structure/v1/companies/5OTBHGR573I4X5TF/ultimate-parent \
  -H "Authorization: Bearer your_access_token"

{
  "veridion_id": "5OTBHGR573I4X5TF",
  "company_name": "Clavorin Materials",
  "result": {
    "ultimate_parent_veridion_id": "NM7ION2QMOLAX2PM",
    "ultimate_parent_company_name": "Quorvex Foods GmbH",
    "ultimate_parent_website_domain": "quorvexfoods.example.com",
    "ultimate_parent_jurisdiction": "de"
  }
}

Location and building IDs work the same way. A location from a company's footprint is the same location when you fetch it by ID, it names the same company, and its building lists it.

Any well-formed ID gets a fake company, including a production Veridion ID: the sandbox never returns real data. An ID that isn't 16 characters gets a 400, as in production.

Lists and pagination

List endpoints paginate as described in Pagination: page_size (default 25, max 200), max_results (up to 10000), cursor, and the result_count, has_more and next_cursor response fields. Totals are realistic, and some companies have empty lists, as real ones do (for example, no products).

To continue a list, send the next_cursor value on its own; it keeps the page_size and max_results of the first call. Changing either while paging gets a 400 on Search and Products & Services (coming soon) and is ignored on Location Intelligence, as in production.

List sizes are the same for every account. In production your account's limits apply, so check them before relying on large pages.

Recognizing sandbox data

Sandbox data is fake on purpose and easy to spot:

• Every response from the sandbox carries the X-Veridion-Sandbox: true header, errors included. A request rejected before it reaches the sandbox, such as a 401 for an invalid or expired token, doesn't carry it.
• Company names are invented, for example Clavorin Materials, Zorbix Dynamics or Quorvex Foods GmbH.
• Websites, email addresses and social links use example.com subdomains, for example https://www.clavorinmaterials.example.com and [email protected].

Phone numbers and registry identifiers such as LEI, EIN and VAT IDs follow real formats but are random, and can coincide with real ones. Don't use them to contact or look up anyone.

Magic test values

Put one of these values in a request to make the sandbox return a specific scenario. They let you test the paths that are hard to trigger on purpose, such as an empty result, a rate limit or a server error.

Magic values are case-insensitive and can appear anywhere in a field, so Acme test-no-match Ltd works too. Use one magic value per request.

Where to put a magic value

Example: handling a rate limit

curl -i -X POST https://data.veridion.com/match/v6/companies \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{"identifiers": {"commercial_names": ["test-rate-limit"]}}'

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-Veridion-Sandbox: true

{
  "path": "/match/v6/companies",
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded: 1 request per second, burst 1. Retry after 1 second."
}

Errors use the same structure as in production. See API Response codes.

ESG processing

In production, ESG data for a company that hasn't been analyzed yet takes a while: the first call starts the analysis and returns a processing session that you poll. Use test-esg-processing as the veridion_id on any single-company ESG endpoint to test that flow.

1. Call the ESG endpoint. It returns processing and a session ID:

   Bash

   curl https://data.veridion.com/esg/v1/companies/test-esg-processing/scores \
     -H "Authorization: Bearer your_access_token"

   JSON

   {
     "veridion_id": "test-esg-processing",
     "status": "processing",
     "active_processing_session": "72854137-337e-40fd-9608-47998d8e7466",
     "last_computed_at": null,
     "result": null
   }

2. Poll the session:

   Bash

   curl https://data.veridion.com/esg/v1/processing/72854137-337e-40fd-9608-47998d8e7466 \
     -H "Authorization: Bearer your_access_token"

   JSON

   {
     "veridion_id": "test-esg-processing",
     "module": "scores",
     "status": "complete",
     "result_count": 1
   }

3. Call the ESG endpoint again. It returns "status": "complete" and the result.

After the result is served, the next call starts a new processing session, so you can run the test again. Each account has its own sessions. If polling a session returns 404, start again from step 1.

Available endpoints

The sandbox serves these endpoints on the same paths as production.

Limits

• Rate limit. 20 requests per second, with bursts up to 30, per account. All your sandbox keys and APIs share it. Above it, the sandbox returns 429 Too Many Requests with Retry-After: 1. This limit only protects the service and isn't your production rate limit; to test how your integration handles that one, use test-rate-limit.
• Credits. None. To test running out of credits, use test-out-of-credits.
• Account limits. The sandbox works the same for every account. Your account's production credits and limits don't apply to it.

Moving to production

1. Replace the sandbox client ID and secret with your production ones. The base URL, paths, requests and response shapes stay the same.
2. Remove magic values from your test data. In production they are ordinary input.
3. Check your account's credits and limits: production calls spend credits and follow your account's limits.