Skip to main content
POST
/
v1
/
onboarding-form
curl -X POST "https://api.affonso.io/v1/onboarding-form" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Affiliate Onboarding",
    "description": "Tell us about how you plan to promote our product.",
    "questions": [
      {
        "question": "Which channels will you use to promote us?",
        "type": "multiple_choice",
        "is_required": true,
        "options": ["YouTube", "Newsletter", "Blog", "Social"],
        "order": 0
      },
      {
        "question": "Tell us about your audience",
        "type": "textarea",
        "is_required": false,
        "order": 1
      }
    ]
  }'

{
  "success": true,
  "data": {
    "id": "cmf8onb0001p3010onbform1",
    "name": "Affiliate Onboarding",
    "description": "Tell us about how you plan to promote our product.",
    "created_at": "2024-04-10T08:00:00.000Z",
    "updated_at": "2024-04-10T08:00:00.000Z",
    "questions": [
      {
        "id": "cmq1onb000onbq1",
        "question": "Which channels will you use to promote us?",
        "type": "multiple_choice",
        "is_required": true,
        "options": ["YouTube", "Newsletter", "Blog", "Social"],
        "order": 0
      },
      {
        "id": "cmq1onb000onbq2",
        "question": "Tell us about your audience",
        "type": "textarea",
        "is_required": false,
        "options": [],
        "order": 1
      }
    ]
  }
}
Each team may only have a single onboarding form. The form and its questions are created atomically: if any question fails validation, the entire operation is rejected. Returns 409 DUPLICATE_ERROR if an onboarding form already exists for your team — use PATCH /v1/onboarding-form to modify it instead.

​
Body Parameters

​
name
string
required
Form display name. Between 1 and 200 characters.
​
description
string | null
Optional description shown above the form. Maximum 1000 characters.
​
questions
array
required
Between 1 and 50 questions. Order is preserved by the order field on each question.

​
Response

Returns the created OnboardingForm object — same shape as GET /v1/onboarding-form. 
curl -X POST "https://api.affonso.io/v1/onboarding-form" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Affiliate Onboarding",
    "description": "Tell us about how you plan to promote our product.",
    "questions": [
      {
        "question": "Which channels will you use to promote us?",
        "type": "multiple_choice",
        "is_required": true,
        "options": ["YouTube", "Newsletter", "Blog", "Social"],
        "order": 0
      },
      {
        "question": "Tell us about your audience",
        "type": "textarea",
        "is_required": false,
        "order": 1
      }
    ]
  }'

{
  "success": true,
  "data": {
    "id": "cmf8onb0001p3010onbform1",
    "name": "Affiliate Onboarding",
    "description": "Tell us about how you plan to promote our product.",
    "created_at": "2024-04-10T08:00:00.000Z",
    "updated_at": "2024-04-10T08:00:00.000Z",
    "questions": [
      {
        "id": "cmq1onb000onbq1",
        "question": "Which channels will you use to promote us?",
        "type": "multiple_choice",
        "is_required": true,
        "options": ["YouTube", "Newsletter", "Blog", "Social"],
        "order": 0
      },
      {
        "id": "cmq1onb000onbq2",
        "question": "Tell us about your audience",
        "type": "textarea",
        "is_required": false,
        "options": [],
        "order": 1
      }
    ]
  }
}

​
Notes

  • Required permission: write:program.
  • single_choice and multiple_choice questions must include a non-empty options array.
  • order does not need to be contiguous, but values are used as-is to sort the form.