Subclients¶

A Subclient is an end user of your program (an individual or a business) as represented in GIB's system. Subclients are associated with your Company and hold one or more Subclient Accounts through which money moves. The full Subclients API surface covers creation, lifecycle management, attachments, and history.

Subclient creation is NOT KYC. You complete CIP through your own program. The Subclient record in GIB is the platform-side anchor for the user relationship, not GIB-conducted identity verification. It is the routing point for Transactions, reconciliation, automated returns, and webhook events.

Subclients give the platform a stable identity for the individuals and businesses you serve. Everything else points back: Transactions link to Subclients; reconciliation records reference them; automated-returns configurations apply at the Subclient-Account level; webhook events carry the relevant Subclient ID.

Getting started: for a step-by-step walkthrough creating a Subclient and provisioning its first Virtual Account, see Create a Subclient with a Virtual Account.

Subclient types¶

The type field has two valid values:

The type drives KYC/KYB obligations on your side (see your CIP responsibilities) and may drive different default configurations.

Subclient relationship¶

The relationship_type field categorizes the Subclient's role in your program. Valid values:

The non-customer types exist primarily to support Subtransactions, the per-end-user "true parties" record on bulk Transactions. When your program bundles many end-user payments into a single rail event (cross-border remittance, mass payouts, marketplace settlements), you'll create Subclients with relationship_type values that reflect the role each party plays in the de-nested flow: customer for the true sender, beneficiary for the true recipient, payment_service_provider for the liquidity provider, affiliate for an international affiliate handling the payout. The Subtransaction itself references two Subclients (an origin and a destination); their relationship_type is what makes monitoring and screening interpret the flow correctly.

Address completeness depends on the relationship_type. For customer, payment_service_provider, affiliate, and root, a Subclient's address must include country_alpha_2_code, city, and street_address_1. For beneficiary and counterparty, only country_alpha_2_code is required.

Lifecycle¶

A Subclient's state field uses one of these four values:

• created: just created, not yet under formal review
• pending: pending review / KYC verification
• approved: verified and able to transact
• rejected: rejected; cannot transact

A Subclient also has an independent active boolean that controls whether it can currently transact (separate from state). Pause a Subclient by calling updateSubclient with active=false; terminate by setting state=rejected.

Webhook events emitted on Subclient state changes use the subclient_* event-type family: subclient_created, subclient_pending, subclient_approved, subclient_rejected, subclient_updated. See Webhooks for the full event-type catalog.

Required fields¶

For business:

• Legal name
• Tax ID (EIN, or SSN for a sole proprietor)
• Address
• Beneficial owners (>= 25% ownership, with KYC docs per owner)
• Officers and key personnel

For natural_person:

• Full legal name
• Date of birth
• Tax ID (SSN/ITIN)
• Address

Attach supporting documents to the Subclient via createSubclientAttachment.

These fields support the Subclient record; they don't replace your CIP. See your responsibilities.

Your CIP must collect the tax ID. The API fields below are optional, until a program setting requires them for your program.

Tax ID and ID document¶

A Subclient and each of its beneficial owners can carry one tax ID and one government-issued ID document, as structured fields:

tin_type is ssn, itin, ein or foreign_tin. identification_type is passport, driver_license, state_id, national_id, alien_registration or other. New values may be added to both lists, so accept values you don't recognize.

A request is rejected when:

• tin comes without tin_type, or the other way round, tin is blank, or a foreign_tin comes without tin_country_alpha_2_code
• identification_type comes without identification_number or without identification_country_alpha_2_code, or identification_number comes without identification_type
• identification_type is other without identification_type_other_description, or a description comes with any other type
• the ID document's country is US and identification_issuing_state is not a 2-letter state code
• a US tax ID (ssn, itin, ein) is not 9 digits once spaces and hyphens are removed, an SSN has area 000, 666 or 900-999, group 00 or serial 0000, or an ITIN does not start with 9

Besides unknown country codes and type values, nothing else is rejected, now or later. An empty string counts as a value, so send null to remove one of these fields. US tax IDs are stored and returned as digits only. A missing tin means it was not provided, never that the person or business has none.

Which number goes where. A number that is both a tax ID and a national ID (Brazil's CPF, Spain's DNI/NIF) goes in tin as a foreign_tin. A national ID that is not a tax ID (Nigeria's NIN) is a national_id document. Don't send a BVN: it identifies a bank customer, not a person.

Masking. Depending on your role, tin comes back in full, with only its last 4 characters showing (✦✦✦✦✦6789), or not at all; identification_number comes back in full, fully masked, or not at all. See Data masking. A masked value sent back is rejected, so echoing a record you read cannot overwrite the stored number.

Attachments keep working. If you send the SSN or TIN as an attachment today, nothing changes. To share your verification provider's result for a person's or owner's identification number or a business EIN, send it as a vendor_output attachment, stripped of anything the result doesn't need.

Your responsibilities vs. GIB's¶

Webhook events¶

See Webhooks for delivery semantics.

Related concepts¶

• Companies & Users, the parent layer
• Subclient Accounts, what each Subclient holds
• Virtual Accounts, the most common Subclient Account type
• Automated Returns, configured per Subclient Account
• Webhooks