DNA Behavior Developer Hub: Complete Guide

The Developer Hub is the central technical resource for developers building on top of DNA Behavior. It covers everything from your first API call to going live as a certified ISV Partner.

Here's what it includes:

• Getting Started — set up your Developer Portal access, get your API keys, and build your first integration
• SDKs & Embeds — embed the Discovery SDK into your website or app
• APIs — the full endpoint reference for retrieving behavioral data
• Troubleshooting — fixes for common API and SDK errors
• ISV Guide — a step-by-step path for partners building licensed behavioral apps

If you're starting from scratch, begin with Developer Portal Access & API Key Setup.

---

Getting Started

Developer Portal Access & API Key Setup

Before any development can begin, you need access to the Developer Portal and a valid API key.

Step 1: Go to the Developer Portal

Visit https://developers.dnabehavior.com/ and click Get Started. Log in with your existing DNA Behavior Web App credentials. No separate signup required. Once logged in, your developer account is automatically created.

Step 2: Check for your API key

After logging in, go to your Profile and scroll to API Keys.

• API key visible → you're ready to go.
• No API key → you need to request access first.

Step 3: Request API access

API access requires enrollment in the Developer Program (ISV Program). Email DNACare@dnabehavior.com with:

• Your company name
• Your account email
• A short description of your use case

Once approved, you'll receive your API keys, endpoint access, integration documentation, and SDK setup support.

→ Full guide: Developer Portal Access & API Key Setup

---

Building Your First Integration

The standard integration follows this six-step sequence. Skipping Steps 2 or 5 causes the majority of production errors.

1. Verify your setup

Call Ping to confirm your credentials before doing anything else.

GET /Accounts/Ping/{AccountId}

A 200 response confirms your subscription key and account ID are valid. Pass the key in the Ocp-Apim-Subscription-Key header.

Optionally, call GetSubscriptionFeaturesByAccountId to confirm which endpoints your plan includes.

GET /Accounts/GetSubscriptionFeaturesByAccountId/{AccountId}

2. Check if the participant already exists

Always check before registering. Skipping this causes duplicate insertion errors.

GET /Discovery/CheckIfParticipantExists/{UserName}

{UserName} is the participant's email address. If found, the response returns personId, creditId, and questionPattern. Store these — you need them for every subsequent call. If the participant already completed discovery, jump to Step 5.

3. Register the participant

If the participant doesn't exist yet, register them.

POST /Discovery/InsertParticipantInAccount

Pass firstName, lastName, email, selfRegistrationId, and questionPattern (must be 11, 17, or 46). The response returns personId and creditId. Store both.

4. Launch the SDK

Embed the Discovery SDK iframe with the participant's details. After the iframe loads, pass the encrypted subscription key via postMessage.

html

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

javascript

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

Listen for the screenChanged event to detect when the questionnaire is done:

javascript

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

For full SDK configuration details: How to Embed the Discovery SDK

5. Confirm discovery completion

Before pulling results, always confirm the discovery is complete.

GET /Discovery/GetDiscoveryStatus/{CreditID}

The response shows scheduled, inProgress, and completed flags for each question model (11, 17, 46). Only proceed when completed is true for the model you used. Many result endpoints return 404 or empty responses if you skip this step.

6. Retrieve behavioral data

With discovery confirmed, call result endpoints using the participant's personId.

Common starting points:

• GetUniqueStyleAndDescription — behavioral style name and plain-language description
• GetBDNA5Scores — five core Business DNA dimensions
• GetFDNA5Scores — five core Financial DNA dimensions
• GetPerformanceGuide — 5 strengths, 3 struggles, 5 performance environment keys
• GetHiringData — 25 hiring and career insights

For the full endpoint list: DNA Behavior Public API: Endpoint Reference Guide

→ Full guide: Building Your First Integration Using DNA Behavior API And Discovery SDK

---

SDKs & Embeds

What Is the Discovery SDK?

The Discovery SDK is an embeddable <iframe> that delivers the full behavioral assessment questionnaire inside your own application. It handles everything — instructions, questions, progress tracking, and the results dashboard — without sending users anywhere else.

You get:

• Compatibility with Angular, React, Vue.js, Svelte, Solid.js, and plain HTML/JavaScript
• Multi-language support (English, Spanish, Portuguese, French, German, Mandarin, Hindi, Urdu, Afrikaans, Dutch, and more)
• Automatic progress tracking — users exit and resume without losing their place
• Direct dashboard access for returning users
• Real-time webhook notifications when discovery completes

It's not a native app component. It's an iframe. That makes setup fast and keeps your infrastructure clean.

→ Full guide: What Is the DNA Behavior Discovery SDK?

---

How to Embed the Discovery SDK

What you need before you start

Store the following securely in a key vault (AWS, Azure, or environment files). Never put these in client-side code or commit them to version control.

Credential	How to get it
accountId	Your DNA Web App settings page
Encryption Key	Submit a support ticket to request it
Subscription Key (DNA API Key)	Available in the Developer Portal — see instructions
selfRegistrationId	Found in your DNA Web App self-registration URL

Note: The SDK must sit behind your own authentication. You're responsible for verifying user identities before the SDK loads.

Encrypting the subscription key

Use the jsencrypt package:

javascript

const publicKey = environment.publicKey; const encryption = new JSEncrypt(); encryption.setPublicKey(publicKey); const encryptedKey = encryption.encrypt(environment.SubscriptionKey);

Environment-specific adjustments

Environment	What to do differently
React Native (WebView)	Use injectJavaScript instead of contentWindow.postMessage()
Next.js (App Router)	Wrap in a 'use client' component; postMessage inside useEffect
Flutter / Android WebView / iOS WKWebView	Use your native JavaScript bridge implementation

Email uniqueness rule

Each email address is treated as a unique participant record. If a user needs to retake the questionnaire (for example, upgrading from the 11-question to the 46-question model), they must use a different email address.

→ Full guide: How to Embed the Discovery SDK: A Step-by-Step Guide

---

Webhook Notifications

Webhooks let you receive real-time notifications when a participant completes their discovery — no polling needed.

Register your webhook

POST /Discovery/RegisterWebhookURL

json

{   "accountId": 1234,   "webhookURL": "https://yourdomain.com/webhook",   "status": true }

Re-submitting with a new URL overwrites the previous registration.

What the payload includes

When a participant completes discovery, the DNA platform POSTs a JSON payload to your URL. It includes PersonID, CreditID, UserName, AccountID, FirstName, LastName, FullName, DiscoveryType, DiscoveryCompletionDate, and tag data.

Your endpoint must return 200 OK to confirm receipt.

If payloads are missed

Use these recovery endpoints:

Endpoint	Use
GET /Accounts/WebhookSync/{AccountId}	Retrieves payloads for participants who may not have triggered your endpoint
GET /Accounts/WebhookSyncAll/{AccountId}	Returns all completed participant payloads — use for full resyncs

---

APIs

Authentication

All requests require your subscription key in the Ocp-Apim-Subscription-Key header. Never pass it as a URL query parameter.

Single vs. Array endpoints

Many endpoints come in two versions. Standard versions return named fields. Array versions return the same data as a flat array — easier to loop through programmatically. Use the Array version for dynamic UI rendering; use the standard version when you need to access specific fields directly.

---

Setup and Validation

Endpoint	Method	What it does
/Accounts/Ping/{AccountId}	GET	Confirms your credentials are valid. Use as a health check at the start of any integration.
/Accounts/GetSubscriptionFeaturesByAccountId/{AccountId}	GET	Returns which endpoints and features are active on your account plan.

---

Participant Management

Endpoint	Method	What it does
/Discovery/CheckIfParticipantExists/{UserName}	GET	Checks if a participant exists by email. Returns personId, creditId, and questionPattern if found.
/Discovery/InsertParticipantInAccount	POST	Registers a new participant. Returns personId and creditId required for all subsequent calls.
/Discovery/GetDiscoveryStatus/{CreditID}	GET	Returns scheduled, inProgress, and completed flags per question model. Always call this before pulling results.

---

Answer Submission

Use these when building a custom questionnaire interface or submitting answers programmatically rather than using the Discovery SDK.

Endpoint	Method	What it does
/Discovery/InsertQuestionAnswer	POST	Submits a single answer for the 46-question flow.
/Discovery/Insert11Q17QAnswers	POST	Submits a single answer for 11 or 17-question flows.
/NaturalBehavior/SubmitAnswers	POST	Submits all 46 answers in one request.
/NaturalBehavior/PostDigitalScanToDatabase	POST	Submits pre-computed T-scores directly. Used for the Digital Scan product only — not the standard discovery flow.
/Discovery/GetQuestionAnswer/{PersonId}	GET	Retrieves saved answers for a participant. Useful for auditing or resuming an incomplete discovery.

→ Submit Answers Format and Request Body

---

Core Identity and Behavioral Profile

Endpoint	Method	What it does
/NaturalBehavior/GetAssessmentResults/{PersonID}	GET	Returns raw T-score data for all behavioral factors. The foundational dataset all other endpoints derive from.
/NaturalBehavior/GetUniqueStyleAndDescription/{PersonID}/{LanguageID}	GET	Returns the participant's behavioral style name and a plain-language description. The most concise behavioral summary available.
/NaturalBehavior/GetUniqueStyleAndDescriptionArray/{PersonID}/{LanguageID}	GET	Same data as an array.

→ Get Assessment Results · Get Unique Style and Description

---

Business DNA (BDNA) Endpoints

Endpoint	Method	What it does
/NaturalBehavior/GetBDNA5Scores/{PersonID}/{LanguageID}	GET	Five core BDNA dimensions: Results vs Relationships, Daring vs Careful, Abstract vs Concrete, Systematic vs Flexible, Promoting vs Operating.
/NaturalBehavior/GetBDNA5ScoresArray/{PersonID}/{LanguageID}	GET	Same data as an array.
/NaturalBehavior/GetBDNAWorkplaceInsights/{PersonID}/{LanguageID}	GET	12 workplace behavioral insights with High/Medium/Low ratings and population percentages.
/Discovery/GetBDNADashboardSetting/{SelfRegistrationId}/{AccountId}	GET	Dashboard configuration flags for the BDNA results screen.

→ Get BDNA 5-Scores

---

Financial DNA (FDNA) Endpoints

Endpoint	Method	What it does
/NaturalBehavior/GetFDNA5Scores/{PersonID}/{LanguageID}	GET	Five core FDNA dimensions: Risk Behavior, Financial Relationship Management, Financial Planning Management, Wealth Building Motivation, Financial Emotional Intelligence.
/NaturalBehavior/GetFDNA5ScoresArray/{PersonID}/{LanguageID}	GET	Same data as an array.
/NaturalBehavior/GetFDNAFinancialPlanningInsights/{PersonId}/{LanguageId}	GET	13 financial planning behavioral insights with High/Medium/Low ratings and population percentages.
/NaturalBehavior/GetRiskAllocation/{PersonID}	GET	Risk score, risk group, and portfolio structure recommendation.
/NaturalBehavior/GetMarketMood/{PersonID}/{PortfolioValue}/{Date}	GET	Real-time behavioral assessment of how an investor is likely reacting to current market conditions.
/NaturalBehavior/GetMarketMoodArray/{PersonID}/{PortfolioValue}/{Date}	GET	Same data as an array.
/NaturalBehavior/GetMarketMoodLite/{RiskScore}/{PortfolioValue}/{Date}	GET	Lightweight market mood. Works without a PersonID — uses a risk score directly.
/NaturalBehavior/GetBehavioralBiases/{PersonID}/{LanguageID}	GET	16 behavioral biases with names, descriptions, and population percentages.
/NaturalBehavior/GetBehavioralBiasesArray/{PersonID}/{LanguageID}	GET	Same data as an array.
/Discovery/GetFDNADashboardSetting/{selfRegistrationId}/{accountId}	GET	Dashboard configuration flags for the FDNA results screen.

→ Get FDNA 5-Scores · Get Risk Allocation

---

Workplace and Hiring Endpoints

Endpoint	Method	What it does
/NaturalBehavior/GetPerformanceGuide/{PersonID}/{LanguageID}	GET	5 strengths, 3 struggles, and 5 performance environment keys for the participant.
/NaturalBehavior/GetPerformanceGuideArray/{PersonID}/{LanguageID}	GET	Same data as an array.
/NaturalBehavior/GetHiringData/{PersonID}	GET	25 hiring insights across talents (10), roles (5), environments (5), and rewards (5).
/NaturalBehavior/GetHiringDataArray/{PersonID}	GET	Same data as an array.
/NaturalBehavior/GetWorkplaceTalentInsights/{PersonID}	GET	19 workplace talent scores including promoting, operating, risk behavior, adaptability, and more.
/NaturalBehavior/GetSalesInsights/{PersonID}	GET	21 sales behavior scores covering new territory, solution-based selling, negotiation, strategic focus, and more.

→ Get Performance Guide · Get Hiring Data · Get Sales Insights · Get Workplace Talent Insights

---

Relationship Intelligence

Endpoint	Method	What it does
/ParticipantProfile/GetStyleMatch/{personId1}/{personId2}	GET	Behavioral compatibility between two participants. Both must have completed their discovery.

---

Reports and Media

Endpoint	Method	What it does
/Discovery/GetVideoUrl/{personId}	GET	Returns the personalized BDNA and FDNA video URLs for the participant.

---

Webhook Management

Endpoint	Method	What it does
/Discovery/RegisterWebhookURL	POST	Register or update a webhook URL for your account.
/Discovery/GetWebhookURLByAccountId/{AccountId}	GET	Retrieve the registered webhook URL and its active status.
/Accounts/WebhookSync/{AccountId}	GET	Manually trigger payload delivery for completed participants whose webhook may not have been received.
/Accounts/WebhookSyncAll/{AccountId}	GET	Same as WebhookSync but for all completed participants. Use for full resyncs.

---

Testing with Postman

Postman is optional but strongly recommended during development. It lets you validate authentication, inspect request and response structures, and debug issues before moving to production code.

The DNA Behavior Postman setup includes a pre-built collection and environment file.

Setup steps:

1. Download the Postman Collection and Environment files from the Postman guide
2. Import both files into Postman
3. Select the imported environment from the dropdown
4. Update subscriptionKey and accountId with your values
5. Send requests immediately

Best practices:

• Use the Secondary Key for testing
• Never commit your subscription key to version control
• Rotate keys periodically
• Treat Postman as a development tool only — not for production

→ Full guide: Postman: Getting Started With The DNA API

---

Troubleshooting

API Errors and Fixes

→ Full guide: Troubleshooting The DNA Behavior API: Common Errors And Fixes

Error	Most common causes	Fix
401 Unauthorized	Key passed in URL instead of header; wrong key for the account; key was rotated and old key still in use; hosting platform stripping custom headers	Pass key in Ocp-Apim-Subscription-Key header; verify key matches the account; check hosting security header settings
403 Forbidden	accountId doesn't match the key; endpoint restricted by plan tier	Verify accountId matches the subscription key; confirm your plan includes the endpoint
404 Not Found	Participant doesn't exist; discovery not yet complete; wrong personId or accountId	Run CheckIfParticipantExists and GetDiscoveryStatus before calling result endpoints
400 Bad Request	Missing required fields; wrong data types; malformed JSON; missing Content-Type: application/json header	Check all required parameters; verify data types match the spec; validate JSON structure
InsertParticipantInAccount failing	Email already registered under the account; missing or wrong fields	Call CheckIfParticipantExists first; verify all required fields
SubmitAnswers / Insert11Q17QAnswers failing	Wrong PersonID or CreditID; questionPattern mismatch; incomplete answer set	Confirm IDs from InsertParticipantInAccount; match questionPattern to the answer set
500 Internal Server Error	Server-side error (not your request)	Retry the request; if persistent, submit a support ticket with accountId, endpoint, and timestamp
Webhook payloads not received	Webhook not registered or status is false; endpoint not publicly accessible; server not returning 200	Verify via GetWebhookURLByAccountId; check your server logs; use WebhookSync or WebhookSyncAll to recover missed payloads
Stale or incorrect response data	Wrong accountId or personId; caching on your end; results not yet processed	Confirm identifiers; clear cache; allow a brief processing window after discovery completion

---

Discovery SDK Issues

→ Full guide: Troubleshooting the Discovery SDK

Issue	Cause	Fix
Blank or error screen on load	Missing or malformed required parameters	Verify all six parameters are present in the iframe URL: accountId, selfRegistrationId, questionPattern (exactly 11/17/46), firstname, lastname, email
Subscription key not transmitting	postMessage not firing; plain key used instead of encrypted key; wrong messageTarget; hosting platform blocking postMessage	Confirm onload fires before iframe completes; encrypt with jsencrypt; check messageTarget is exactly https://embeddiscovery.dnabehavior.com/
postMessage not working in React Native WebView	Known React Native WebView limitation — contentWindow.postMessage() is not supported	Use injectJavaScript to pass the encrypted key
iframe not rendering in Next.js	Component rendering server-side	Add 'use client' directive; wrap postMessage in useEffect
iframe blocked by Content Security Policy	CSP headers don't allow the SDK origin	Add frame-src https://embeddiscovery.dnabehavior.com; to your CSP
User can't retake the questionnaire	Email addresses are unique records — one discovery per email	User must complete discovery with a different email address or an alias
Progress not saving between sessions	Email parameter inconsistent across sessions	Ensure the same email is passed to the iframe on every session for the same user
Results dashboard not displaying	screenChanged event listener not registered before questionnaire completion	Register the event listener before the questionnaire starts
Multiple accounts not working correctly	Credentials from different accounts being mixed	Map the correct accountId, selfRegistrationId, and subscriptionKey to each account before passing to iframe parameters

---

ISV Partner Program

What Is an ISV Partner?

An Independent Software Vendor (ISV) Partner is an organization that incorporates DNA Behavior's behavioral technology directly into their own business application or enterprise platform. You choose from a library of behavioral and financial insights, embed them into your product, and deliver personalized behavioral intelligence to your end users.

The ISV Partner Program has three tiers: Silver, Gold, and Platinum.

→ Full guide: 1. Start Here: ISV Partner Program 101

---

ISV Partner Tiers

→ Full guide: What's the Difference Between Silver, Gold, and Platinum ISV?

Benefit	ISV Silver (Financial DNA)	ISV Silver (Business DNA)	ISV Gold	ISV Platinum
Basic Insights	Yes	Yes	Yes	Yes
Premium Insights (Financial)	Yes	—	Yes	Yes
Premium Insights (Business)	—	Yes	Yes	Yes
Speaking Opportunities at DNA Events	—	—	Yes	Yes
Access to Additional Insights (Paid SOW)	—	—	Yes	Yes
Shared Participant Records	—	—	—	Yes
Sandbox Access	—	—	Yes	Yes
IP Address Filtering	—	—	—	Yes
Advisory Board	—	—	—	Inquire
IT Escrow	—	—	—	Inquire

---

ISV Partner Readiness

Before signing up, DNA Behavior recommends completing these readiness steps.

→ Full guide: ISV Partner Readiness

Leadership readiness:

• Elect a Responsible Manager as the main point of contact for all partner communications and accreditation training
• Elect a Chief Behavioral Officer (CBO) and register them for Certification Training with a certified DNA Behavior trainer

Firm readiness:

• Establish your legal entity, financial and legal structure
• Define your business scope, target market, and ideal customers
• Prepare a Business Plan and a "Category King" Marketing Plan that demonstrates clear market differentiation
• Write a whitepaper documenting your thesis on how behavior drives performance in your specific context
• Prepare a Product Plan (DNA Behavior IP Usage Application) with tech specs, architecture diagrams, branding mockups, security and privacy approach, and a development timetable

Technology stack used by successful ISVs:

• Hosting: Microsoft Azure or Amazon AWS
• Office Systems: Microsoft 365 or Google Suite
• CRM & Marketing: HubSpot
• Billing: Chargify (SaaS) / Stripe (credit card transactions)

---

Developer Portal and API Access (ISV)

→ Full guide: 2. ISV Developer Portal and Accessing the DNA API

Step 2.1 — Sign up for a Professional Package

Sign up at dnabehavior.com/platform-pricing. A 14-day free trial is included and extended as long as your ISV subscription is active. Choose your Named User (lead developer) carefully — changes require additional steps.

Step 2.2 — Create your developer account

Go to developers.dnabehavior.com and sign in using the same credentials as your DNA Web App account. You'll receive a confirmation email.

Step 2.3 — Request your developer account be linked to your ISV contract

Submit an ISV support ticket to request your account be upgraded to a full ISV developer account. Include the username from Steps 2.1 and 2.2. Once upgraded, your API keys will be available on the Developer Portal Profile page.

Changing who holds the API keys:

1. Elevate the new person to a Named User in the DNA Web App — follow these steps
2. Have them complete Steps 2.1 and 2.2
3. The existing key holder must authorize the change in writing by submitting an ISV form

---

Accessing Your DNA API Keys (ISV)

→ Full guide: 3. Accessing the DNA API Keys

Keys are how the DNA API authenticates your requests. Here's what you need to know:

• Keys are issued per developer, not per team. Choose your developer carefully.
• You receive a Primary Key and a Secondary Key. Use one or both depending on your setup.
• Keys are found on the Profile page of the Developer Portal.
• You can regenerate your keys at any time from the portal.
• Keys are only issued after completing Step 2.

---

Pre-Seeded Case Studies for API Practice

→ Full guide: 4. Using Pre-Seeded Case Studies in Your DNA App Account for API Practice

When you onboard as an ISV Partner, your DNA App account includes pre-seeded behavioral profiles representing a variety of Natural Behavior Styles. Use these to test API calls without real participant data.

Sample profiles included:

Name	Natural Behavior Style	Prod PersonID
Alicia Davies	Community Builder	7f566574-2581-43fd-b045-a14fbc911aa2
Carlos Valdez	Adapter	929c8afd-094e-424c-b63c-0e86dab06dfd
Elizabeth Smith	Strategist	2a4c1319-1264-4760-9baf-71b76c49c358
Hugh Massie	Initiator	f3344929-1c64-4f2e-bab1-61cee5229f32
Mary Evans	Reflective Thinker	82fb5e83-9eb7-4d12-9268-d737ad8f2e95
Michael Rodriguez	Engager	08ebb78d-4f8f-4d34-a1d6-c27e08e4a8f2
Nora Valdez	Influencer	d6514210-c2b2-438e-827c-c3672ef1442b
Raj Kapoor	Relationship Builder	5a752120-77f8-4092-8cc4-7ac8423dc239
Robert Davies	Initiator	dd5b1f3d-56c5-4c64-996e-1d6e028242f6

For sandbox PersonIDs and the full profile table, see the full guide linked above.

How to run a test call:

1. Log in at developers.dnabehavior.com
2. Click API → Public API
3. Select GetUniqueStyleAndDescription (a good starting point)
4. Click Try it and paste a PersonID from the table above
5. Enter 22 in the LanguageID field (US English)
6. Click Send — a 200 OK response confirms your setup is working

The DNA Web App is powered by the same API. Comparing API responses with what you see in the app is the fastest way to understand how behavioral insights translate to a real product.

---

Designing a Unique MVP

→ Full guide: 5. Designing a Unique MVP: A Guide for ISV Partners of DNA Behavior

ISV Partners are required to build genuinely differentiated products. DNA Behavior's IP can make up no more than 20% of your on-screen experience — your unique technology must account for the remaining 80%.

Four phases of MVP design:

1. Define the business challenge

Identify the specific pain point you're solving. Build a thesis on how behavioral insights drive performance or a measurable outcome in your target industry.

2. Leverage DNA API insights

Understand which endpoints and behavioral dimensions are most relevant to your use case. Know what the data means before you build around it.

3. Build wireframes

Visualize the structure, user flow, and interactions of your MVP. Focus on a user-friendly experience that communicates your unique value clearly.

4. Develop UI mockups

Bring wireframes to life. Align your visual design with your industry's branding while keeping a distinct product identity.

DNA Behavior prohibits copying or re-skinning its on-screen experience for resale in similar industries. Build something that disrupts your market — not something that replicates what already exists.

---

Going Live Checklist

→ Full guide: Going Live Checklist

Before launching your DNA API integration:

1. Complete the onboarding questionnaire — submit the onboarding survey. If you submitted at the start of your build, re-submit with your final product features so the DNA Behavior team can review your app accurately.
2. Validity and QA check — contact DNA Behavior Support to receive the validity report for your integration. Submit a ticket here.

---

Transitioning from Version 1 to Version 2

→ Full guide: Guide for ISV Partners: Transitioning from DNA Behavior Version 1 to Version 2

If you were on Version 1 (hosted on dnabehavior.biz domains), here are the key changes for migrating to Version 2.

New base URL

• Production: https://api.dnabehavior.com/

Authentication

Version 2 uses API key-based authentication. Tokens are no longer supported. Follow the steps at ISV Developer Portal and Accessing the DNA API and Accessing the DNA API Keys.

Submit Answers API

The system now assigns the PersonID on a successful 200 response. You no longer assign it manually.

Get Hiring API — updated role names and IDs

New hiring roles and IDs were introduced in V2. Renamed roles include: Administrator, Designer, Event Planner, Inside Sales, Operations Manager, Outside Sales, Product Developer, Project Manager, Compliance and Quality Control, Recruiter, Trainer/Teacher. New roles added: Sales Manager, Engineer, Accountant, Technician, Author, Counsellor, Enforcement and Protection, Operations Support, Marketing & Communications, Customer Support, Business Promotion.

Migration impact

• You'll receive a new Account ID.
• All participants receive new Person IDs. Export the updated IDs from the DNA Web App (export guide) to update your system for historical GET calls.
• Match records between versions using the email address (username in both systems) and Person ID (GUID format in both systems).

Note: Version 1 reports are not available via the API in Version 2. PDF reports are also not exposed via the API under the ISV partner agreement.

---

Summary: Correct Integration Call Sequence

If you take nothing else from this article, follow this sequence every time:

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

Skipping Steps 2 or 5 accounts for the vast majority of issues seen in production integrations.