Skip to content
  • There are no suggestions because the search field is empty.

Building Your First Integration Using DNA Behavior API And Discovery SDK

The SDK handles the questionnaire. Your API calls register the participant before and retrieve their behavioral data after.

Overview of the Flow

  1. Verify your setup
  2. Register the participant
  3. Launch the SDK
  4. Confirm discovery completion
  5. Retrieve behavioral data

Step 1: Verify Your Setup

Before doing anything else, confirm your credentials are working.

Call Ping with your accountId:

GET /Accounts/Ping/{AccountId}

A 200 response confirms your subscription key and account ID are valid. If this fails, check that your subscription key is being passed in the Ocp-Apim-Subscription-Key header and that the account ID is correct.

Optionally, call GetSubscriptionFeaturesByAccountId to confirm which features and endpoints are active on your account before building against them.

GET /Accounts/GetSubscriptionFeaturesByAccountId/{AccountId}

Step 2: Check if the Participant Already Exists

Before registering a participant, check whether they already exist in the platform using their email address.

GET /Discovery/CheckIfParticipantExists/{UserName}

Where {UserName} is the participant's email address.

If the participant exists, the response returns their personId, creditId, and questionPattern. Store these. You will need them later.

If the participant does not exist, proceed to Step 3.

If the participant already exists and has completed their discovery, skip to Step 5.

Step 3: Register the Participant

If the participant does not yet exist, register them under your account.

POST /Discovery/InsertParticipantInAccount

Request body:

{   "firstName": "string",   "lastName": "string",   "email": "string",   "selfRegistrationId": 0,   "questionPattern": 46 }

questionPattern must be 11, 17, or 46. Choose based on the discovery type you are offering.

On success, the response returns:

{   "personId": "string",   "creditId": 0,   "questionPattern": "string" }

Store personId and creditId. These are the two identifiers you will use for all subsequent API calls for this participant.

Step 4: Launch the SDK

With personId confirmed and credentials ready, embed the SDK iframe and pass the required parameters.

<iframe src="https://embeddiscovery.dnabehavior.com/?accountId={accountId} &selfRegistrationId={selfRegistrationId} &questionPattern={questionPattern} &firstname={firstname} &lastname={lastname} &email={email}" height="1080px" width="1920px"> </iframe>

After the iframe loads, pass the encrypted subscription key via postMessage:

iframe.onload = () => {   const encryptedKey = 'YOUR_ENCRYPTED_KEY';   iframe.contentWindow?.postMessage(     encryptedKey,     'https://embeddiscovery.dnabehavior.com/'   ); };

The SDK will handle the full questionnaire experience from here. Refer to the SDK embed guide for full configuration details.

To detect when the participant has completed the questionnaire, listen for the screenChanged event:

window.addEventListener('message', (event) => {   if (event.data === 'dashboard') {     // Discovery complete. Proceed to pull results.   } });

Step 5: Confirm Discovery Completion

Before pulling results, confirm the discovery is marked as complete. Do not skip this step. Many result endpoints return 404 or empty responses if the discovery has not finished processing.

GET /Discovery/GetDiscoveryStatus/{CreditID}

The response shows the status for each question model:

{   "q11Model": { "scheduled": false, "inProgress": false, "completed": false },   "q17Model": { "scheduled": false, "inProgress": false, "completed": false },   "q46Model": { "scheduled": false, "inProgress": false, "completed": true } }

Only proceed when completed is true for the model you used.

Step 6: Retrieve Behavioral Data

With discovery confirmed as complete, you can now call any result endpoint using the participant's personId.

The endpoint you call depends on what your integration needs. Below is a summary of the most commonly used result endpoints and what they return.

Behavioral identity

GetUniqueStyleAndDescription returns the participant's behavioral style name and a plain-language description. This is the most concise summary of who someone is behaviorally and a good starting point for most integrations.

Business DNA results

GetBDNA5Scores returns the five core Business DNA dimensions: Results vs Relationships, Daring vs Careful, Abstract vs Concrete, Systematic vs Flexible, and Promoting vs Operating.

GetBDNAWorkplaceInsights returns 12 workplace behavioral insights with High, Medium, or Low ratings and population percentages.

Financial DNA results

GetFDNA5Scores returns the five core Financial DNA dimensions: Risk Behavior, Financial Relationship Management, Financial Planning Management, Wealth Building Motivation, and Financial Emotional Intelligence.

GetRiskAllocation returns the participant's risk score, risk group, and portfolio structure recommendation.

GetMarketMood returns a real-time behavioral assessment of how the participant is likely reacting to current market conditions. Requires portfolio value and date in addition to personId.

Workplace and hiring

GetPerformanceGuide returns 5 strengths, 3 struggles, and 5 performance environment keys.

GetHiringData returns 25 hiring and career insights across talents, roles, environments, and rewards.

For the full list of available result endpoints, refer to the API Endpoint Reference Guide.

Optional: Set Up Webhook Notifications

Instead of polling GetDiscoveryStatus, you can register a webhook to receive an automatic notification when a participant completes their discovery.

POST /Discovery/RegisterWebhookURL
{   "accountId": 0,   "webhookURL": "https://yourdomain.com/webhook",   "status": true }

Once registered, the DNA platform will POST a payload to your URL on every completion. The payload includes contact details, behavioral scores, communication keys, and preferred contact method.

If you miss a payload, use WebhookSync to manually retrieve completions for your account.

Summary: Correct Call Sequence

  1. Ping to verify credentials
  2. CheckIfParticipantExists to avoid duplicate registrations
  3. InsertParticipantInAccount if the participant is new
  4. Launch the SDK iframe with the participant's details
  5. GetDiscoveryStatus to confirm completion before pulling results
  6. Call the relevant result endpoints using personId

Following this sequence prevents the most common integration errors. Skipping Steps 2 or 5 accounts for the majority of issues seen in production integrations.

Still need help?

Submit a support ticket here. Include the endpoint you are calling, your accountId, and any error responses you are receiving. Do not include your subscription key or encryption key in the ticket.