Telling Conduit the subject is a person
Both the requirements endpoint and the submit endpoint take an optionalsubjectType. Send individual to onboard a natural person:
subjectType means a business — permanently. It is not a temporary default: an application that never sends the parameter is a business onboarding, and always will be. A business integration that predates individual support needs no change.
What an individual owes
An individual application names exactly one person — the account holder — underownership.persons[], with the role ACCOUNT_HOLDER. A crypto-wallet or virtual-account request for an individual that names more than one person returns 400 VALIDATION_ERROR at /ownership/persons, and files nothing. That person carries the same identity fields a business’s control person does: legal name, date of birth, nationality, and residential address. The account holder must be at least 18 and at most 120 years old. The account holder also sends the expiry date of the identity document your provider verified, and that date must not be in the past. Every individual also sends a tax identifier. Alongside those identity fields, an individual sends two things a business collects at the entity level:
- Activity and due-diligence descriptors — an
activityobject: the account holder’s occupation and occupation category, the purpose of the account, source of funds, expected monthly volume and transaction count, and the countries they transact with. The requirements response lists which apply. The purpose, source of funds, occupation category, volume, transaction count and countries carry closed sets of accepted values; occupation and the optional employer name are free text. Where enhanced due diligence applies, the requirements response also listssourceOfWealth, which takes the same closed set as source of funds. When it containsOther,sourceOfWealthOtheris required and says what the source is. - Consent — a
certification.termsAndConditionsacknowledgement.
businessInfo, registeredAddress, operatingAddress, companyClassification, businessActivity, compliance, or relatedCompany. The subject is a person, not a company, so sending any of them is rejected, and the requirements response for an individual never lists them.
Conduit does not onboard an account holder who lives in, or is a national of, a country it does not serve: discovery answers 404 for that country of residence and leaves those countries out of the allowedValues, and submit refuses them with 422 RESIDENCE_NOT_SUPPORTED or NATIONALITY_NOT_SUPPORTED.
Tax identifier
Every individual sendstaxIdType, taxIdNumber and taxIdCountry. taxIdCountry is the country that issued the identifier. It can differ from the person’s nationality and from where they live. Discovery lists the taxIdType values that apply to the person.
Discovery does not know the person’s nationality unless you tell it. Add the optional
nationality query parameter (alpha-2 or alpha-3) to the requirements call with subjectType=individual to get the answer for that person. Without it, discovery asks every person for a tax identifier and lists every type the person could send: SSN and ITIN for a person who lives in the United States, and SSN with the non-US types for a person who lives elsewhere. Submit applies the table above to the nationality in the application. Sending nationality with a business subjectType returns 400.
Submit refuses an SSN whose first three digits are 000, 666 or 900 to 999, whose middle two digits are 00, or whose last four digits are 0000, because the US never issues those numbers as an SSN. A malformed SSN or ITIN returns 422 ONBOARDING_NOT_READY at /ownership/persons/0/taxIdNumber, in the same list as the other field problems. Send nine digits. Dashes and spaces are removed before the number is checked. If the person’s number is an ITIN, send it with taxIdType ITIN.
Identifiers that are not accepted
Conduit refuses some national identification numbers. The country that issued the identifier decides, not where the person lives.
Conduit ignores spaces, dashes, dots and slashes, and letter case, when it checks these numbers. A
NATIONAL_ID from any other country, such as SGP or HKG, is accepted. A PASSPORT issued by CAN is accepted for a person who lives in CAN. A NATIONAL_ID issued by CAN is refused for a person who lives in DEU.
Submit refuses the application with 422 ONBOARDING_NOT_READY before it creates anything. The detail names what to send instead and never repeats the number you sent:
/ownership/persons/0/taxIdNumber. An update to an existing individual customer that makes the identifier fail any rule in the table is refused with 400 VALIDATION_ERROR and the same detail, and nothing is stored.
Phone number
Send the account holder’sphoneNumber in E.164 format, for example +14155551234. A national number is also accepted when the person’s address.country can complete it, for example (408) 555-0166 for a person who lives in the US. The number must be one that the country’s numbering plan issues: the country calling code must exist, and the rest of the number must have a length and a range that the country uses. A number of another country is accepted, for example a UK number for a person who lives in the US. The customer reads the number back as you sent it.
A number that cannot be read for that country returns 422 ONBOARDING_NOT_READY with errors[].pointer /ownership/persons/0/phoneNumber and the detail “Phone Number is not a valid phone number for USA. Send it in international format, for example +14155551234.” An international number that no country issues, for example +999 1234567 or +1 000 000 0000, gets the detail “Phone Number is not a valid phone number in any country. …”. A customer update checks a phone number only when the update sends it.
Verifying the person’s identity
Individual onboarding must be enabled for your organization. Contact your Conduit account manager. You verify the account holder with your own identity-verification provider and upload one identity verification attestation for them, and the original government ID the provider verified: the front, and the back as a second file if the document has one. Attach every id toownership.persons[0].documentIds[]. See What You’re Verifying → Person-level evidence for what the report must contain, and Upload each person’s attestation and ID for the upload calls. There is no Conduit-hosted identity check for an individual: Conduit issues the person no verification link.
Send the date your provider completed the verification in ownership.persons[0].identityVerificationDate (YYYY-MM-DD), as the report shows it. The field is optional, but we strongly recommend it. The verification must be less than a year old, and the review checks it on this date. Without it, approval depends on reading the date from the report, and the application can wait for a manual review. When the report’s date differs from the date you send by more than a few days, the application also waits for a manual review.
If individual onboarding is not enabled for your organization, both the requirements call and the submit call return 422 SUBJECT_REQUIREMENTS_NOT_AVAILABLE. Do not retry. Conduit enables individual onboarding for your organization after a review, separately for sandbox and live. You cannot turn it on yourself. Contact your Conduit account manager.
Where enhanced due diligence applies, two more requirements appear, at different levels. A proof-of-address document is listed on the account holder’s individualRequirements[] row — attach it to ownership.persons[0].documentIds[]. Enhanced financial evidence is a customer-level requirement: the top-level documents[] checklist carries a bank-statement row with its own minCount — three months of statements where individual enhanced due diligence applies — so attach that many document ids to the top-level documentIds[], not to the person. (The top-level minDocuments is only the floor of one document; the row’s own minCount is the count that matters here.) Review checks the proof of address and the bank statements, not submit, in the same way as the enhanced due diligence evidence below.
Enhanced due diligence
Some individuals need enhanced due diligence. The requirements response for a country listsactivity.sourceOfWealth as required and adds an EDD_EVIDENCE row to the account holder’s documents[] when the country of residence calls for it. The requirements response is built from the country and nationality only, so it does not show a need that comes from other answers in the application. When your submission makes enhanced due diligence apply, submit refuses a missing activity.sourceOfWealth with a 422 at /activity/sourceOfWealth, and the application is not approved until it has the evidence document. An application that needs it stays in processing until an operator has reviewed it, so approval takes longer than for other individuals. The application.approved or application.rejected webhook reports the decision.
Upload one evidence document with POST /v2/documents, sending type=EDD_EVIDENCE and eddEvidenceKind as multipart fields, then attach the returned id to ownership.persons[0].documentIds[]. eddEvidenceKind is required with that type and refused with any other.
A customer update that makes enhanced due diligence apply owes the same as onboarding. This occurs when the update gives a reason for enhanced due diligence that the customer did not have before: it declares the person politically exposed, or it moves the residence to a country that calls for it. This also applies to a customer who already needs enhanced due diligence for the other reason. The update must give activity.sourceOfWealth, unless the customer already has one. If it does not, the update returns 400 VALIDATION_ERROR at /activity/sourceOfWealth. Send the evidence document, and the proof of address for a new residence, in ownership.persons[0].documentIds[] with the account holder’s id. Send the bank statements in the top-level documentIds[]. The update stays in processing until an operator has reviewed it. An update that does not make enhanced due diligence apply, for example a new phone number, is reviewed as before.
A document that is older than its window, or that shows no issue date where one is needed, is asked for again.