Getting Started
This guide introduces the core concepts of the MagFi platform and provides an overview of the standard integration flow.
Core Concepts
Organization
Your organization is the top-level entity that represents you (the partner) on the platform. All customer enterprises live under your organization.
- Provisioned by the MagFi team during initial setup
- Identified by an
organizationId - A service
userIdis also provided for administrative operations
Enterprise
An enterprise is the main representation of your customer inside the platform. One customer = one enterprise.
- Enterprises represent both individuals (natural persons) and corporations
- Often called a child enterprise because it lives under your organization
- When you create an enterprise, the response returns both an
enterpriseIdand auserId— store both - The
enterpriseIdis your primary identifier for all subsequent operations
User
Users represent access, not customers. A user defines who can access a given enterprise.
- When you create an enterprise, a
userIdis automatically generated and returned — use this one - In most integrations, you won't need to manage users directly; the platform handles it
- The service
userIdcan be provided by the MagFi team for specific operations
The userId returned when you create an enterprise belongs to that customer enterprise and is different from your service userId. In most integrations, enterpriseId is the main customer identifier, but you should store both values.
Identity
The identity is a living document attached to an enterprise. It holds the KYC/KYB data for that customer.
- An enterprise can be created without an identity — you register the enterprise first, then submit identity data separately
- For US citizens, documents are often not required — verification handles it automatically. Documents are only requested for non-US citizens or when there's a data mismatch
- The
enterpriseCreated: falseflag on an identity means the KYC/KYB process is not yet complete
Go Account
The Go Account is a multi-asset wallet that enables both fiat and crypto operations for a customer.
- Created with
type: "trading"— this automatically generates the required sub-wallets (e.g., Bitcoin, USD) - Can only be created after KYC is approved
- You can generate new deposit addresses inside the Go Account as needed
Integration Overview
The standard integration follows these steps. Each step is covered in detail in its own guide.
Document upload is not part of every onboarding flow. Many US customers move from enterprise creation to identity submission, signatures, and approval without uploading documents. Documents are usually only needed for non-US citizens or when verification data does not match.
| Step | What | Guide |
|---|---|---|
| 1-6 | Create enterprise, verify identity (KYC), sign terms, create Go Account | User Onboarding |
| 7-8 | Link bank account, fund via ACH or crypto deposit | Funding |
| 9 | Buy or sell Bitcoin with USD | Conversions |
| 10 | Send USD to bank or crypto to external address | Withdrawals |
Key ID Reference
| Concept | ID Field | Source |
|---|---|---|
| Your organization | organizationId | Provisioned by MagFi |
| Service account | userId (service) | Provided by MagFi |
| Customer | enterpriseId | Returned from POST /enterprise |
| KYC record | identityId | Returned from POST /identity |
| Go Account | goAccountId | Returned from POST /ofc/wallet/generate |
Next Steps
- User Onboarding — Create enterprise, verify identity, open a Go Account
- Funding — Link a bank account, deposit USD or receive Bitcoin
- Conversions — Buy or sell Bitcoin
- Withdrawals — Send funds out