17-Question Discovery API

The 17-Question Discovery is DNA Behavior's short-form behavioral discovery. It identifies a person's Natural Behavior and Unique Style from 17 forced-choice questions, then returns practical insights on strengths, communication, decision-making and financial behavior.

The API lets you run the Discovery inside your own product. You own the experience. DNA Behavior processes the answers and returns the results.

Who does what

Role	Responsibility
Participant	Completes the Discovery. Provides name, email and answers to the 17 questions.
Client	The company building the experience, and its developers. Hosts the front end, calls the API, stores participant identifiers, and decides how results are presented.
DNA Behavior	Provides the API, question content and scoring methodology. Processes answers and returns results. Acts as data processor for participant data.

The flow

Step	Action	Endpoint
1	Load account configuration	Get Account Details
2	Check if the participant exists	CheckIfParticipantExists
3	Register new participant and store identifiers	InsertParticipantInAccount
4	Submit each answer (17 calls)	Insert11Q17QAnswers
5	Retrieve and display results	Results endpoints

Before you start

DNA Behavior provides the following during onboarding:

Item	Description
Account ID	Identifies your organization.
Self Registration ID	Identifies your registration configuration. Controls which Discovery and results sections apply.
Language ID	Sets the language of returned results.
Access details	Credentials and environment details required to call the API.
Question content	The 17 questions and options, in your supported languages.

Base URL: https://api.dnabehavior.com

Response format. Every endpoint returns the same envelope. Always check statusCode in the response body, not only the HTTP status.

Field	Type	Description
message	string	"Success" or "Error"
data	object	The result of the call
errors	object	Present on failure. Contains message, debugMessage and collections.
statusCode	integer	200 on success. Check this, not just the HTTP status.

Implementation rules

Call the API from your backend. Keep credentials, identifiers and participant data out of browser code.
Store identifiers permanently. Keep personId, creditId and the participant's email together in your database. You need them for answer submission and every future results lookup.
Treat results as personal data. Apply the same controls you use for other personal information.

Step 1: Load account configuration

Method	Path
GET	/private-no-auth/Accounts/GetAccountDetailsByAccountIdandSelfregId/{accountId}/{selfRegistrationId}

Call this when the experience loads. It returns:

Field	Type	Description
primaryColor	string	Brand primary color (hex)
secondaryColor	string	Brand secondary color (hex)
logo	string	Logo URL
discoveryType	string	Discovery type, for example "WorkTalent"
workTalentDashboardDto.isVideo	boolean	Show Unique Style video
workTalentDashboardDto.isViewReport	boolean	Show report
workTalentDashboardDto.isBDNA5KeyWorkTalents	boolean	Show key work talents
workTalentDashboardDto.isDesiredTaskBasedTalent	boolean	Show task-based talents
workTalentDashboardDto.isPGuide	boolean	Show Performance Guide
workTalentDashboardDto.isTopTwoTraits	boolean	Show top two traits

Only show sections whose flag is true.

Step 2: Check and register the participant

Check if participant exists

Method	Path
GET	/prod-public-api/Discovery/CheckIfParticipantExists/{email}

URL-encode the email, particularly addresses containing "+".

Result	What you see	What to do
Not found	statusCode 500, errors.collections.user = "User Does not exist."	Continue to registration
Exists	statusCode 200	Don't register again. Use the personId stored in your system to retrieve results.
Any other error	statusCode not 200	Treat as an error and retry

If an existing participant needs a new Discovery, contact DNA Behavior.

Register the participant

Method	Path
POST	/prod-public-api/Discovery/InsertParticipantInAccount

Request body (JSON)

Field	Type	Example	Description
firstName	string	Alex	Participant first name
middleName	string	(blank)	Optional
lastName	string	Taylor	Participant last name
email	string	participant@example.com	Participant email
selfRegistrationId	integer	2000	Your Self Registration ID
questionPattern	integer	17	Always 17 for this Discovery

Response: 200 OK

Field	Type	Example	Store?
personId	string (GUID)	3f2a9c1e-0000-4000-8000-000000000000	Yes, permanently. Used to retrieve results.
creditId	integer	100001	Yes, permanently. Used to submit answers.
questionPattern	string	"17"	No

Store the participant's email alongside personId and creditId.

A 400 means invalid or missing fields; check errors.collections. A 500 means registration failed; log errors.message and retry after checking existence again.

Step 3: Submit the 17 answers

Each question shows three descriptors. The participant picks the one Most like them and the one Least like them. Send each answer as soon as it is given, one call per question.

Method	Path
POST	/prod-public-api/Discovery/Insert11Q17QAnswers

Request body (JSON)

Field	Type	Example	Description
creditID	integer	100001	The creditId returned at registration
parentID	integer	5	Question identifier (see table below)
question	object		Contains most and least
question.most	integer	1	Option chosen as Most: 1, 2 or 3
question.least	integer	2	Option chosen as Least: 1, 2 or 3
questionPattern	string	"17"	Always "17"

Response: 200 OK. message "Success", data "Submitted successfully".

Field casing: this endpoint uses creditID and parentID with a capital "ID". Registration returns creditId. Match the casing shown for each endpoint.

Question order and parentIDs

Question	parentID	Question	parentID
1	5	10	27
2	6	11	31
3	8	12	33
4	16	13	35
5	17	14	36
6	21	15	37
7	22	16	38
8	23	17	40
9	26

Answer rules

Every question needs exactly one Most and one Least, and they must be different options.
Don't move to the next question until the current answer returns statusCode 200.
Encourage instinctive responses. The Discovery reflects how a person naturally behaves, not how they think they should.
Submit all 17 answers before requesting results.

Step 4: Retrieve results

Once all 17 answers are submitted, retrieve results using the participant's personId. All paths below start with /prod-public-api.

Check which sections to show

Endpoint	Path
Work dashboard settings	GET /Discovery/GetBDNADashboardSetting/{selfRegistrationId}/{accountId}
Financial dashboard settings	GET /Discovery/GetFDNADashboardSetting/{selfRegistrationId}/{accountId}
Subscription features	GET /Accounts/GetSubscriptionFeaturesByAccountId/{accountId}

Each setting is a true/false flag, such as isPGuide, isBDNA5KeyWorkTalents, isFDNA5Score, isBehavioralBiases and isMarketMood. Only show the sections that are enabled.

Results endpoints. {languageId} sets the language of the returned text.

Insight	Path	Returns
Unique Style	GET /NaturalBehavior/GetUniqueStyleAndDescriptionArray/{personId}/{languageId}	Unique Style name and description
Performance Guide	GET /NaturalBehavior/GetPerformanceGuideArray/{personId}/{languageId}	Strengths, struggles, environment keys
Work Factors (BDNA5)	GET /NaturalBehavior/GetBDNA5ScoresArray/{personId}/{languageId}	Five Factor scores
Financial Factors (FDNA5)	GET /NaturalBehavior/GetFDNA5ScoresArray/{personId}/{languageId}	Five financial Factor scores
Behavioral Biases	GET /NaturalBehavior/GetBehavioralBiasesArray/{personId}/{languageId}	Ranked biases
Market Mood	GET /NaturalBehavior/GetMarketMoodArray/{personId}/{marketPercentage}/{dd-MM-yyyy}	Risk group, mood and market guidance
Talents	GET /NaturalBehavior/GetHiringDataArray/{personId}	Ranked talents, roles, environments, rewards
Video	GET /Discovery/GetVideoUrl/{personId}	Work and financial Unique Style videos

Response fields

Insight	Fields returned in data
Unique Style	behaviorTypeID, behaviorTypeName (e.g. "Initiator"), behaviorTypeDescription
Performance Guide	strengths, struggles, environmentKeys. Each is a list of items with id, description, detailedDescription.
Work Factors (BDNA5)	resultsVsRelationships, daringVsCareful, abstractVsConcrete, systematicVsFlexible, promotingVsOperating. Each has value (0 to 100), label and description.
Financial Factors (FDNA5)	riskBehavior, financialRelationshipManagement, financialPlanningManagement, wealthBuildingMotivation, financialEmotionalIntelligence. Each has value (0 to 100) and description.
Behavioral Biases	behavioralBias1, behavioralBias2 and so on, in ranked order. Each has biasID, name, description, population.
Market Mood	riskScore, riskGroup, mood, color, behavioralTypeName, marketMoodDescriptions (heading plus list of guidance lines)
Talents	talents, roles, environments, rewards. Each is a ranked list of items with id, name, value.
Video	bdnaVideo, fdnaVideo (URLs)

All results responses also return personID, creditID and languageID.

Presenting results responsibly

Describe results as natural tendencies and preferences, not fixed traits or predictions.
Avoid language such as "you will always" or "you cannot".
Results are not a medical or psychological diagnosis. Don't present them as one.
Use the descriptions DNA Behavior returns rather than rewriting their meaning.

Error handling

Situation	What you see	What to do
Participant not found	statusCode 500, errors.collections.user = "User Does not exist."	Continue to registration
Invalid request	400 Bad Request	Check fields and types against the step above
Request failed	message "Error", statusCode not 200	Log errors.message server-side and show a friendly retry message
Answer not accepted	Non-200 on Insert11Q17QAnswers	Don't advance. Retry, then show an error.
Network timeout	No response	Retry with backoff. Check existence before re-registering.

Never show raw error text to participants.

Go-live checklist

#	Check	Owner
1	Account ID, Self Registration ID, Language ID and access details received	Client
2	All API calls made from your backend	Client
3	personId, creditId and email stored permanently and linked	Client
4	"Participant not found" handled as a normal path	Client
5	All 17 answers submitted with correct parentIDs	Client
6	Results sections follow the dashboard settings	Client
7	Results wording follows the responsible presentation guidance	Client
8	End-to-end test participant completed and results verified	Client and DNA Behavior