Getting started

Follow these steps to integrate the Explore API into your system. Steps 1 and 3 are handled by the TelmarHelixa team once your agreement is in place; the rest are yours.

Before you start

You need a signed agreement and licensed dataset access before provisioning begins. If you do not have one yet, contact your Sales Rep — that is step zero, and everything below waits on it.

The six steps

Account provisioning

Us

Ensure users who will call the API have a TelmarHelixa account with licensed dataset access enabled. Accounts are provisioned by the TelmarHelixa Sales team.

You tell us:

• which licensed datasets and surveys you need,
• which authorization groups apply,
• which environments you want (sandbox, production, or both).

Survey codes look like M20F and you will send them in the body of every crosstab request.

tip

Ask for a sandbox environment even if you only plan to run in production. It gives you somewhere safe to test error handling before you go live.

You now have TelmarHelixa accounts with licensed dataset access

Developer Portal access

You

Your technical team signs in to the Developer Portal using their Cognito credentials (provided by Sales).

The portal provides:

1. Your API key (sent as the Telmar-Engine-Authorizer header).
2. Links to the Swagger / OpenAPI documentation for this service.

Portal access uses Cognito login only — SSO is not currently enabled for the portal itself. See Authentication.

Treat the API key as a secret

Store the API key in your secret manager immediately. Never commit it or ship it to a browser. If it is exposed, rotate it in the portal.

You now have API key and links to the live docs

Permissioning

Us

All users requiring survey access must be permissioned against their licensed datasets. The TelmarHelixa team handles auth enablement and survey-level permissions.

Calling a survey you are not entitled to returns 403 even with a valid API key. Permissioning must be configured before any API queries can be made.

note

Adding a survey later is a commercial change, not a technical one. It is a conversation with Sales, not a support ticket.

You now have survey-level permissions attached

Embed the API

You

Retrieve your API key from the Developer Portal and embed the RESTful API into your local or cloud-hosted services:

First call — sample data

curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "SurveyCode": "M20F",
    "AuthorizationGroup": "_ALL_",
    "PopulationBaseCode": "AR18_24",
    "TargetCodes": ["OMEN", "OWOMEN"]
  }'

A 200 with ResultCode: 0 and a Results array means you are integrated. If you get a 401 or 403 instead, the authentication guide covers both. Full request and response shapes — including the errors — are in the endpoint how-to.

Keep the API key server-side

Never put the API key in front-end code. Proxy through your own backend and let it hold the secret.

You now have a working first call from your own code

Build the UI (if required)

You

This step is optional — plenty of integrations are server-to-server and stop at step 4.

If you are building a front-end UI to expose codebook querying, recommended capabilities are:

• survey selection,
• data category and item selection,
• boolean logic creation,
• row / column function configuration.

Also:

• Call OPTIONS /crosstab first to confirm the CORS policy for your origin.
• Never put the API key in front-end code. Proxy through your own backend.

warning

An API key shipped to a browser is a disclosed secret, whatever the bundler does to it. Always proxy.

You now have a front-end that exposes codebook querying

Post usage billing

Both

Once live, usage is tracked and billed monthly based on API call volume and the size of data returned.

• Usage is unlimited in terms of number of runs.
• Billing is per call and scales with the volume of data returned.
• Commercial terms — including per-call cost, tiers and minimum commitments — are defined separately with Sales and are not published on this site.

Commercial terms live with Sales

Contact your Sales Rep for pricing, contract length and volume options. Your agreement is the authority.

You now have monthly usage-based invoices

Useful links

Developer Portal	developer.telmar.com
Auth docs	Telmar API Authentication
Base URL	https://engines.api.telmar.com/omg/prd/v1

What to read next

• Authentication — Cognito, SSO for API calls, and the API key header.
• Endpoint how-to — every request and response shape, with copyable examples.
• Endpoint reference — parameters, schemas and status codes.

Contact Sales

Request access

Open in Developer Portal ↗Authentication docs ↗