AdvisorFind Matching API

Server-to-server integration · v1

1. Store your token on your server

Set ADVISORFIND_API_TOKEN in your server’s secret environment. Send it in the Authorization header. Do not put it in browser code, URLs, or logs. It grants matching access only; it does not grant admin or advisor-account access. Tokens remain valid until revoked in Admin → API access.

2. Verify authentication

curl https://platform.advisorfind.com/v1/token -H "Authorization: Bearer $ADVISORFIND_API_TOKEN"

This does not call an AI model.

3. Send client JSON

Save this as client.json. Use exact field names and enum values. Booleans must be true/false, not strings. No location is needed.

{
  "client": {
    "ageRange": "55to64",
    "hasRetirementAccounts": true,
    "married": true,
    "childrenUnder18": false,
    "retirement": "preparing",
    "approach": "balanced",
    "assetBand": "500to2",
    "priorities": [
      "income",
      "tax"
    ],
    "firstName": "Alex",
    "notes": "I own a business and want help planning retirement income and reducing tax surprises."
  }
}

curl https://platform.advisorfind.com/v1/matches \
  -H "Authorization: Bearer $ADVISORFIND_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data @client.json

Field	Required?	Values / meaning
`ageRange`	Required	under35, 35to44, 45to54, 55to64, 65plus
`hasRetirementAccounts`	Required	boolean
`married`	Required	boolean
`childrenUnder18`	Required	boolean
`retirement`	Required	notsoon, preparing, retired
`approach`	Required	preservation, balanced, growth
`assetBand`	Required	under250, 250to500, 500to2, 2to5, over5
`priorities`	Required	enough, income, risk, tax, aligned
`firstName`	Optional	Optional; nonblank, no control characters. Returned as metadata, not used to rank.
`notes`	Optional	Optional free-form survey answer, used by AI matching.
`investableAssets`	Optional	Optional exact USD assets; must be within assetBand. Bands: under250 [0,250000); 250to500 [250000,500000); 500to2 [500000,2000000); 2to5 [2000000,5000000); over5 [5000000,infinity).

Priorities: enough = retirement readiness; income = retirement income; risk = investment risk; tax = tax planning; aligned = portfolio alignment. Client priorities are unranked.

Asset bands: under250 = below $250k; 250to500 = $250k to below $500k; 500to2 = $500k to below $2M; 2to5 = $2M to below $5M; over5 = $5M or more. If supplied, investableAssets must be a whole number within that band.

firstName: at most 100 characters. notes: at most 2,200 characters. Extra fields are rejected. Request limit: 32 KB.

4. Read results

Illustrative response; IDs and scores below are examples, not guaranteed matches.

{
  "requestId": "example-request-id",
  "advisorIds": [
    "01",
    "07",
    "12"
  ],
  "matches": [
    {
      "advisorId": "01",
      "rank": 1,
      "fitScore": 92
    },
    {
      "advisorId": "07",
      "rank": 2,
      "fitScore": 85
    },
    {
      "advisorId": "12",
      "rank": 3,
      "fitScore": 78
    }
  ],
  "status": "matched",
  "firstName": "Alex",
  "eligibleCount": 8,
  "provider": "typesafe",
  "model": "jev-latest",
  "fallbackUsed": false,
  "warnings": [],
  "elapsedMs": 180
}

advisorIds are the simple, permanent IDs from the Advisor Network page. Keep them as strings to preserve leading zeros. The first ID is the highest-ranked introduction. Map these IDs to the advisor profiles on your consumer website.

fitScore is 0–100 when supplied by TypeSafe; it is null for OpenAI or survey fallback. It is not a probability or an advisor’s permanent score. provider identifies the configured service; model identifies the model actually used. Do not hard-code model names.

Matching uses the provider selected in admin. If AI matching is unavailable, fallbackUsed is true and survey-based matching is returned; free-form notes are not evaluated in that fallback. Check warnings.

When fewer than three eligible advisors exist, status is insufficient_matches and the arrays contain 0–2 advisors. We never fabricate IDs or return disabled advisors. Display a suitable alternative to the user if the list is empty.

Errors and retries

{"error":{"code":"unauthorized","message":"The API token is invalid or revoked."},"requestId":"..."}

400: Invalid JSON or client fields
401: Missing, invalid, or revoked token
409: Advisor availability changed; retry
413: Request body exceeds 32 KB
415: Content-Type must be application/json
429: Rate limit or another match in progress; honor Retry-After
500: Unexpected server failure
503: Matching unavailable

Limit: 60 authenticated API requests per minute per token, including token checks. The platform currently processes one match at a time; overlapping requests return 429 with Retry-After: 2. Queue requests on your server and retry 429/409/503/500 with bounded backoff (for example, up to three attempts). Use a 45-second HTTP timeout. Do not retry 400/401/413/415 without correcting the request. Requests are not idempotent: retrying a timed-out match may invoke matching again.

Matching tokens cannot read advisor email addresses, edit profiles, or access API-provider credentials. Client answers are sent to the configured matching provider; avoid unrelated sensitive details in notes. This API does not provide a public advisor directory or browser CORS access.