Back to Guides

Quickstart

Create your first rollover in under 5 minutes. This guide walks you through getting your API key, fetching available partners, and submitting your first rollover request.

5 min read

What You'll Build

By the end of this guide, you'll have successfully created a 401(k) rollover request via the TrustRails API. The rollover will appear in your dashboard, and you can track its progress through the state machine.

5 minutes

to complete

3 API calls

to create a rollover

No SDK required

standard REST API

Prerequisites

  • A TrustRails account with API access enabled
  • An API key (you'll generate one in Step 1)
  • cURL, Postman, or any HTTP client
1

Get Your API Key

Generate an API key from the Integration Portal.

Navigate to the Integration Portal and locate the API & Webhooks tab. Click Generate New Key to create an API key.

Integration Portal showing the API Keys section with the 'Generate New Key' button

Your API key will look like this:

tr_test_ak_VG5vFYOILAuuxcy7KqhQGtAh83k36UH9
2

Get Available Partners

Fetch the list of verified destination custodians.

Before creating a rollover, you need to know which destination custodians are available. The /v1/partners endpoint returns all verified partners.

curl -X GET "https://api.trust-rails.com/v1/partners?active=true&verified=true" \
  -H "Authorization: Bearer tr_test_ak_YOUR_API_KEY" \
  -H "Content-Type: application/json"

The response includes each partner's ID, name, EIN, level, and supported account types:

JSON
{
  "data": [
    {
      "id": "7cf9ab0a-3b37-4c25-bf60-2d9ade0b5085",
      "name": "Vanguard",
      "ein": "23-1945930",
      "level": 1,
      "supportedAccountTypes": ["TRADITIONAL_IRA", "ROTH_IRA"],
      "verified": true,
      "active": true
    },
    {
      "id": "57ccba24-eb08-4664-9847-c03fa9797264",
      "name": "Fidelity",
      "ein": "04-2571508",
      "level": 2,
      "supportedAccountTypes": ["TRADITIONAL_IRA", "ROTH_IRA", "SEP_IRA"],
      "verified": true,
      "active": true
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "hasNext": false }
}

Understanding Partner Levels

Level 1

Standard Settlement

Traditional fund transfer via ACH/wire. Custodians handle settlement directly.

Level 2

Smart Contract Settlement

Blockchain-secured transfers with on-chain escrow and automated compliance verification.

Alternative: Search for Participant's 401(k) Plan

If the participant doesn't know their current 401(k) custodian, you can search for their employer's retirement plan using our DOL plan search API. This returns the plan's custodian EIN, which you can match to a partner.

cURL
curl -X GET "https://api.trust-rails.com/v1/plans/search?q=Acme%20Corporation" \
  -H "Authorization: Bearer tr_test_ak_YOUR_API_KEY"

Response includes the plan's custodian EIN:

JSON
{
  "data": [
    {
      "planName": "Acme Corporation 401(k) Plan",
      "sponsorName": "Acme Corporation",
      "ein": "12-3456789",
      "custodianEin": "23-1945930",
      "custodianName": "Vanguard",
      "participantCount": 1250
    }
  ]
}

Match the custodianEin from the plan response to the ein field in the partners list to identify the source custodian.

3

Create a Rollover

Submit a rollover request with participant and account details.

Now you're ready to create your first rollover. The POST /v1/rollovers endpoint accepts participant information, source account details, and destination account configuration.

curl -X POST "https://api.trust-rails.com/v1/rollovers" \
  -H "Authorization: Bearer tr_test_ak_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "ssn": "123-45-6789",
      "dateOfBirth": "1985-06-15"
    },
    "sourceAccount": {
      "custodianName": "Previous Employer 401k",
      "accountNumber": "ACC-123456",
      "accountType": "TRADITIONAL_401K"
    },
    "destinationAccount": {
      "custodianId": "7cf9ab0a-3b37-4c25-bf60-2d9ade0b5085",
      "accountNumber": "NEW-789012",
      "accountType": "TRADITIONAL_IRA"
    },
    "rolloverDetails": {
      "type": "FULL"
    }
  }'

A successful response returns the created rollover with its initial state:

JSON
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "state": "started",
  "createdAt": "2025-01-30T10:30:00Z",
  "participant": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "sourceAccount": {
    "custodianName": "Previous Employer 401k",
    "accountType": "TRADITIONAL_401K"
  },
  "destinationAccount": {
    "custodianId": "7cf9ab0a-3b37-4c25-bf60-2d9ade0b5085",
    "custodianName": "Vanguard",
    "accountType": "TRADITIONAL_IRA"
  }
}

Success! Your rollover has been created.

SSN Security & Confidential Vault

The Social Security Number (SSN) you submit is never stored in plain text. It is immediately encrypted using AES-256 and stored in our SOC 2 compliant confidential vault.

The SSN is only decrypted when required for regulatory compliance (e.g., IRS reporting, custodian verification). Access is strictly audited and requires explicit authorization.

4

Check Your Dashboard

Verify your rollover appears in the TrustRails dashboard.

Head back to your TrustRails dashboard. You should see the newly created rollover in your transfers list with a
Started
status.
TrustRails dashboard showing the newly created rollover in the transfers list

Click on the rollover to view its details, including the current state, available actions, and event timeline.

What's Next?

Congratulations! You've created your first rollover via the API. Here's what to explore next:

Authentication Guide

Learn about API key types, environments, and security best practices.

API & Integration

Learn about REST, GraphQL, webhooks, and testing tools.

Want Access to All Guides?

Schedule a call to get your API keys and full access to our integration guides.