Skip to content
Logo

GET /customers/:id/kyc/associated-persons/:person_id/link-suggestions

The same human is often both an individual customer of yours and a beneficial owner on a business customer's KYB profile. This endpoint finds them: it returns the individual customers in your organization whose identity matches one associated person exactly, so you can link the two and have Seismic verify that human once instead of twice.

Set a returned customer_id on that person via PUT /customers/:id/kyc/profile to accept a suggestion — see Linking a person to an individual customer for the link's semantics.

Matching is exact, never fuzzy. A customer is suggested only when it agrees with the person on at least one of:

  • tax_id (compared with formatting removed, so 123-45-6789 and 123456789 agree),
  • email (case-insensitive), or
  • first_name and last_name (case-insensitive) and date_of_birth.

An associated person carrying none of those details has nothing to match on, and the response is an empty list.

id must be a business customer, and person_id must be an associated person on its KYB profile.

Response 200

Suggestions are ordered strongest first — a customer agreeing on more details leads the list. The customer the person is already linked to stays in the list, flagged with linked.

{
  "suggestions": [
    {
      "customer_id": "6f2b4b6e-7b0e-4a5a-9a7a-2d4d5f0c1b33",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "matched_on": [
        "tax_id",
        "email"
      ],
      "kyc_status": "approved",
      "linked": false
    }
  ]
}
FieldTypeNotes
customer_idstring (UUID)The suggested individual customer. Send this as customer_id on the associated person to link them.
first_name, last_name, emailstringOmitted when the customer's profile doesn't carry them.
matched_onarray of stringEvery detail the two records agree on: tax_id, email, name_and_date_of_birth. Never empty.
kyc_statusstringThe suggested customer's own verification status, e.g. approved.
linkedbooleanThis customer is the one the person is linked to today.

Errors

  • 404: unknown customer id, a customer that isn't a business, or a person_id that isn't on its KYB profile.

Example

curl "$SEISMIC_ORCHESTRATION_URL/v0/customers/$CUSTOMER_ID/kyc/associated-persons/$PERSON_ID/link-suggestions" \
  -H "Api-Key: $SEISMIC_ORCHESTRATION_API_KEY"