Skip to main content

Creating Questionnaires

Create custom questionnaires to collect the specific information your compliance processes require.

Basic Structure​

Create a Questionnaire​

curl -X POST https://api.bytrustgate.com/v1/questionnaires \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Risk Assessment",
    "description": "Assess customer risk profile for onboarding",
    "version": "1.0",
    "status": "active",
    "settings": {
      "allow_save_progress": true,
      "show_progress_bar": true,
      "randomize_options": false
    },
    "questions": [...]
  }'

Response​

{
  "id": "quest_123456",
  "name": "Customer Risk Assessment",
  "version": "1.0",
  "status": "active",
  "question_count": 10,
  "created_at": "2025-01-20T14:00:00Z",
  "created_by": "admin@company.com"
}

Adding Questions​

Single Question​

{
  "questions": [
    {
      "id": "purpose",
      "type": "single_choice",
      "question": "What is the primary purpose of your account?",
      "description": "Select the option that best describes your intended use",
      "required": true,
      "options": [
        {"value": "personal", "label": "Personal use"},
        {"value": "business", "label": "Business use"},
        {"value": "investment", "label": "Investment"},
        {"value": "savings", "label": "Savings"}
      ]
    }
  ]
}

Multiple Questions​

curl -X POST https://api.bytrustgate.com/v1/questionnaires \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Source of Funds Declaration",
    "questions": [
      {
        "id": "sof_primary",
        "type": "single_choice",
        "question": "What is the primary source of your funds?",
        "required": true,
        "options": [
          {"value": "employment", "label": "Employment income"},
          {"value": "business", "label": "Business income"},
          {"value": "investments", "label": "Investment returns"},
          {"value": "inheritance", "label": "Inheritance"},
          {"value": "gift", "label": "Gift"},
          {"value": "other", "label": "Other"}
        ]
      },
      {
        "id": "sof_other_details",
        "type": "text",
        "question": "Please describe your other source of funds",
        "required": true,
        "show_if": {
          "question_id": "sof_primary",
          "operator": "eq",
          "value": "other"
        }
      },
      {
        "id": "employer_name",
        "type": "text",
        "question": "What is your employer name?",
        "required": true,
        "show_if": {
          "question_id": "sof_primary",
          "operator": "eq",
          "value": "employment"
        }
      },
      {
        "id": "annual_income",
        "type": "single_choice",
        "question": "What is your approximate annual income?",
        "required": true,
        "options": [
          {"value": "under_50k", "label": "Under $50,000"},
          {"value": "50k_100k", "label": "$50,000 - $100,000"},
          {"value": "100k_250k", "label": "$100,000 - $250,000"},
          {"value": "over_250k", "label": "Over $250,000"}
        ]
      },
      {
        "id": "expected_volume",
        "type": "single_choice",
        "question": "What is your expected monthly transaction volume?",
        "required": true,
        "options": [
          {"value": "under_10k", "label": "Under $10,000"},
          {"value": "10k_50k", "label": "$10,000 - $50,000"},
          {"value": "50k_100k", "label": "$50,000 - $100,000"},
          {"value": "over_100k", "label": "Over $100,000"}
        ]
      }
    ]
  }'

Conditional Logic​

Show/Hide Questions​

{
  "id": "business_details",
  "type": "text",
  "question": "Describe your business activities",
  "show_if": {
    "question_id": "sof_primary",
    "operator": "eq",
    "value": "business"
  }
}

Complex Conditions​

{
  "id": "enhanced_verification",
  "type": "file_upload",
  "question": "Please upload proof of your source of funds",
  "show_if": {
    "any": [
      {
        "question_id": "expected_volume",
        "operator": "eq",
        "value": "over_100k"
      },
      {
        "question_id": "sof_primary",
        "operator": "in",
        "value": ["inheritance", "gift", "other"]
      }
    ]
  }
}

Condition Operators​

OperatorDescriptionExample
eqEquals"value": "employment"
neqNot equals"value": "other"
inIn list"value": ["a", "b"]
ninNot in list"value": ["x", "y"]
gtGreater than"value": 100000
gteGreater or equal"value": 50000
ltLess than"value": 10000
containsContains string"value": "crypto"

Question Sections​

Organize with Sections​

curl -X POST https://api.bytrustgate.com/v1/questionnaires \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comprehensive KYC Questionnaire",
    "sections": [
      {
        "id": "section_personal",
        "title": "Personal Information",
        "description": "Basic personal details",
        "questions": [
          {
            "id": "occupation",
            "type": "text",
            "question": "What is your occupation?"
          }
        ]
      },
      {
        "id": "section_financial",
        "title": "Financial Information",
        "description": "Source of funds and expected activity",
        "questions": [
          {
            "id": "income_source",
            "type": "single_choice",
            "question": "Primary income source",
            "options": [...]
          }
        ]
      },
      {
        "id": "section_risk",
        "title": "Risk Assessment",
        "description": "Additional information for risk assessment",
        "show_if": {
          "field": "applicant.risk_score",
          "operator": "gte",
          "value": 50
        },
        "questions": [...]
      }
    ]
  }'

Validation Rules​

Required Fields​

{
  "id": "email",
  "type": "email",
  "question": "Contact email address",
  "required": true,
  "validation": {
    "error_message": "Please provide a valid email address"
  }
}

Custom Validation​

{
  "id": "amount",
  "type": "number",
  "question": "Expected monthly deposit amount",
  "validation": {
    "min": 0,
    "max": 10000000,
    "error_message": "Amount must be between 0 and 10,000,000"
  }
}

Pattern Validation​

{
  "id": "tax_id",
  "type": "text",
  "question": "Tax ID / SSN",
  "validation": {
    "pattern": "^\\d{3}-\\d{2}-\\d{4}$",
    "error_message": "Please enter in format XXX-XX-XXXX"
  }
}

Triggers and Assignment​

Always Assign​

{
  "trigger": {
    "type": "always"
  }
}

Conditional Assignment​

{
  "trigger": {
    "type": "conditional",
    "conditions": {
      "all": [
        {"field": "risk_score", "operator": "gte", "value": 60},
        {"field": "country", "operator": "in", "value": ["high_risk_countries"]}
      ]
    }
  }
}

Manual Assignment​

{
  "trigger": {
    "type": "manual"
  }
}

Managing Questionnaires​

Update Questionnaire​

curl -X PATCH https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "status": "active"
  }'

Add Questions​

curl -X POST https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id}/questions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [
      {
        "id": "new_question",
        "type": "text",
        "question": "New question text",
        "position": 5
      }
    ]
  }'

Version Control​

curl -X POST https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id}/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "2.0",
    "changes_description": "Added cryptocurrency source option"
  }'

Archive Questionnaire​

curl -X PATCH https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "archived"
  }'

Testing Questionnaires​

Preview Mode​

curl -X POST https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id}/preview \
  -H "Authorization: Bearer YOUR_API_KEY"

Test with Sample Data​

curl -X POST https://api.bytrustgate.com/v1/questionnaires/{questionnaire_id}/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_data": {
      "applicant": {
        "risk_score": 75,
        "country": "US"
      }
    },
    "responses": {
      "sof_primary": "employment",
      "annual_income": "100k_250k"
    }
  }'

Next Steps​