Skip to main content

Data Migration Guide for Account Owners

Migration steps​

There are three main steps to complete the migration:

  1. Submit required claims for each legal person
  2. Run verification using the appropriate workflow
  3. Monitor verification outcome and the legal person's decision

Step 1: Submit required claims​

For each legal person missing data, submit the following claims using:

Endpoint: POST /v0/legal-persons/{legal-person-id}/claims

Claim / Data FieldApplicable To
US citizen confirmationIndividuals, Sole Traders, Officers of LTD
Tax residenciesIndividuals, Sole Traders, LTDs, Officers of LTD
Tax Identification Numbers (TINs)Individuals, Sole Traders, LTDs, Officers of LTD
Standard Industrial Classification (SIC) codeSole Traders and LTDs
Business sizeSole Traders and LTDs
Business typeSole Traders
Risk ratingIndividuals, Sole Traders, LTDs (Reliance only)
warning

Note: For LTD Companies, you need to submit claims for:

  1. The company entity itself
  2. Each officer/director of the company

1. US citizen confirmation​

Confirm whether the individual is a US citizen.

Applicable Workflows:

  • All Individual workflows (Reliance and Verify)
  • All Sole Trader workflows (Reliance and Verify)
  • All LTD Company workflows - for Officers/Directors only

Claim Type: us-citizen

Rules:

  • Must be a boolean value (true or false)
  • Required for all individuals regardless of tax residency

Example:

{
  "claim-type": "us-citizen",
  "us-citizen?": false
}

2. Tax residencies​

Collect all countries where the person or entity is a tax resident.

Applicable Workflows:

  • All Individual, Sole Trader, and LTD Company workflows
  • For LTDs: applies to both the company and its Officers/Directors

Claim Type: tax-residencies

Rules:

  • Must provide at least one country code
  • Use ISO 3166-1 alpha-2 country codes (e.g., "GB", "US", "FR")
  • Can specify multiple tax residencies

Example:

{
  "claim-type": "tax-residencies",
  "tax-residencies": ["GB", "US"]
}

3. Tax identification numbers (TINs)​

Provide TINs for each country of tax residency.

Who do we need to submit a TIN for?

Applicable Workflows:

  • All Individual, Sole Trader, and LTD Company workflows
  • For LTDs: applies to both the company and its Officers/Directors

Claim Type: tax-identification-numbers-by-country

Rules:

  • For individuals and companies with GB-only tax residents: Send an empty map
  • For GB sole traders with annual turnover over £90,000: A GB TIN must be provided
  • A US TIN is required for all US citizens
  • Format varies by country (e.g., Social Security Number (US SSN), Numéro Fiscal de Référence (FR SPI))
  • Can provide multiple TINs per country if applicable

TIN categories​

Whether a TIN is required depends on the country of tax residency. Countries fall into one of three categories:

CategoryDescriptionWhat to submit
TIN requiredA TIN must always be providedSubmit TIN in tins-by-country
TIN required unless exemptA TIN should be provided where availableSubmit TIN in tins-by-country, or a reason code in tin-exemptions-by-country if unavailable
TIN not requiredNo TIN is neededSubmit TIN in tins-by-country or omit the country

See the GJRA country list to check which category applies to each country.

warning

A country must not appear in both tins-by-country and tin-exemptions-by-country

Reason codes​

If a TIN cannot be provided for a country in the TIN required unless exempt category, submit one of the following reason codes in tin-exemptions-by-country:

CodeDescriptionExplanation required
jurisdiction-does-not-issue-tinsThe jurisdiction does not issue TINs to its residentsNo
unable-to-obtain-a-tinThe account holder is unable to obtain a TINYes — provide a free-text explanation in tin-exemption-explanations-by-country
no-tin-required-by-domestic-lawNo TIN is required by the domestic law of the jurisdictionNo
warning

Not having a TIN to hand is not sufficient — a reason code is only valid where a TIN genuinely does not exist.

Examples​

Individual GB-only tax resident - no TIN is needed:

{
  "claim-type": "tax-identification-numbers-by-country",
  "tins-by-country": {}
}

GB sole trader with annual turnover over £90,000 — TIN provided for GB:

{
  "claim-type": "tax-identification-numbers-by-country",
  "tins-by-country": {
    "GB": ["AA123456"]
  }
}

Multiple TINs across countries:

{
  "claim-type": "tax-identification-numbers-by-country",
  "tins-by-country": {
    "US": ["123-45-6789"],
    "FR": ["302 321 760 0000", "12345678901"]
  }
}

TIN required unless exempt — reason code provided instead of a TIN:

{
  "claim-type": "tax-identification-numbers-by-country",
  "tins-by-country": {
    "US": ["123-45-6789"]
  },
  "tin-exemptions-by-country": {
    "IN": "jurisdiction-does-not-issue-tins"
  }
}

TIN required unless exempt — with explanation:

{
  "claim-type": "tax-identification-numbers-by-country",
  "tins-by-country": {
    "US": ["123-45-6789"]
  },
  "tin-exemptions-by-country": {
    "AU": "unable-to-obtain-a-tin"
  },
  "tin-exemption-explanations-by-country": {
    "AU": "Account holder recently relocated and has not yet been issued a TIN by the Australian Taxation Office."
  }
}

4. Standard industrial classification (SIC) code​

Code to classify businesses by their main economic activity.

Applicable Workflows:

  • All Sole Trader workflows
  • Reliance LTD Company - Account Owners (for the company entity)
  • Reliance LTD Company + PSC only - Account Owners (for the company entity)

Claim Type: sic-codes

Rules:

  • 5-digit code
  • Provided as an array (even for a single code)

Example:

{
  "claim-type": "sic-codes",
  "sic-codes": ["12345"]
}

5. Business size​

Business size classification.

Applicable Workflows:

  • All Sole Trader workflows
  • All LTD Company workflows (for the company entity, not officers)

Claim Type: business-size

Rules:

  • Possible values:
    • micro - employs fewer than 10 persons and whose annual turnover and/or annual balance sheet total does not exceed EUR 2 million.
    • small - employs fewer than 50 persons and whose annual turnover and/or annual balance sheet total does not exceed EUR 10 million
    • medium - employ fewer than 250 persons and have an annual turnover not exceeding EUR 50 million, and/or an annual balance sheet total not exceeding EUR 43 million
    • large - anything above medium categorisation

Example:

{
  "claim-type": "business-size",
  "business-size": "small"
}

6. Business type​

Business type classification for Sole Trader customers.

Applicable Workflows:

  • All Sole Trader workflows

Claim Type: business-type

Rules:

  • Value: sole-trader

Example:

{
  "claim-type": "business-type",
  "business-type": "sole-trader"
}

7. Risk rating (Reliance only)​

Risk rating defined for your customer.

Applicable Workflows:

  • Reliance Individual - Account Owners
  • Reliance Sole Trader - Account Owners
  • Reliance LTD Company - Account Owners (for the company entity)
  • Reliance LTD Company + PSC only - Account Owners (for the company entity)

Claim Type: external-risk-rating

Rules:

  • Possible values:
    • low-risk
    • medium-risk
    • high-risk
    • prohibited-risk

Example:

{
  "claim-type": "external-risk-rating",
  "external-risk-rating": "low-risk"
}

Step 2: Run verification​

After submitting all required claims, you must run a verification to validate the new information.

2.1 Retrieve your workflows​

First, retrieve and cache your workflow URLs. If you've already cached your workflows, you'll need to retrieve them again after the new Account Owners workflows have been provisioned. These workflow URLs remain constant after retrieval and should be stored for reuse throughout the migration process.

Endpoint: GET /v0/organizations/{organization-id}/workflows

Example:

curl "https://api.griffin.com/v0/organizations/${ORGANIZATION_ID}/workflows" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Response:

{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "Individual - Account Owners",
      "legal-person-type": "individual"
    }
  ]
}

2.2 Workflow selection guide​

Choose the correct workflow:

If you use this workflowNow you need to use this workflow
Reliance LTD CompanyReliance LTD Company - Account Owners
Reliance LTD Company - PSC onlyReliance LTD Company + PSC only - Account Owners
Reliance Sole TraderReliance Sole Trader - Account Owners
Reliance IndividualReliance Individual - Account Owners
LTD CompanyLTD Company - Account Owners
LTD Company LandlordLTD Company + Landlord - Account Owners
LTD Company PropertyLTD Company + Property - Account Owners
Sole Trader PropertySole Trader + Property - Account Owners
Sole Trader DefaultSole Trader - Account Owners
Individual + Bank VerificationIndividual + Bank Verification - Account Owners
Individual LandlordIndividual + Landlord - Account Owners
Individual DefaultIndividual - Account Owners

2.3 Submit verification​

Submit the legal person for re-verification using the appropriate Account Owners workflow. This re-verification will not impact your customers' usage of the platform; they will continue to make payments and open bank accounts while the verification is processing. Be sure to save the verification-url returned in the response for monitoring purposes.

Endpoint: POST /v0/legal-persons/{legal-person-id}/verifications

warning

Note: For LTD Companies, you need to run verification only for the company entity itself.

Example Request:

curl -X POST "https://api.griffin.com/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45/verifications" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA"
  }'

Example Response:

{
  "created-at": "2026-01-21T10:47:51.959Z",
  "display-name": "DAVIS, Henry",
  "legal-person-type": "individual",
  "legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
  "updated-at": "2026-01-21T10:47:51.959Z",
  "verification-status": "pending",
  "verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
  "workflow-url": "/v0/workflows/wf.W1NwgL6sXCmB3u9cPiJoKQ"
}

Step 3: Monitor verification and decision​

The verification process validates the submitted claims. You must monitor both the verification status and the legal person's application status to confirm successful migration. Wait for the verification status to reach "checks-complete", then monitor the legal person's application status until it shows "accepted".

Verification status values​

StatusDescription
pendingVerification created but processing has not begun
in-progressVerification checks are actively being performed
checks-completeVerification has successfully completed all required checks
checks-declinedVerification was terminated due to failing one or more checks
failedAn internal system error occurred during verification

Application status values​

StatusDescription
submittedApplication has been submitted
referredApplication sent to manual review
acceptedApplication accepted
declinedApplication declined
erroredApplication is in an errored state

For more details, check the onboarding guides.

Migration checklist​

Use this checklist to track migration progress for each legal person.

Step 1: Submit required claims

Submit all applicable claims via POST /v0/legal-persons/{legal-person-id}/claims:

  • us-citizen (for Individuals, Sole Traders, Officers)
  • tax-residencies (all entity types)
  • tax-identification-numbers-by-country (all entity types)
  • sic-codes (Sole Traders and LTDs only)
  • business-size (Sole Traders and LTDs only)
  • business-type (Sole Traders only)
  • external-risk-rating (Reliance workflows only)

Step 2: Run verification

  • Retrieve workflow URLs: GET /v0/organizations/{org-id}/workflows
  • Select the appropriate workflow
  • Submit verification: POST /v0/legal-persons/{legal-person-id}/verifications
  • Save returned verification-url

Step 3: Monitor completion

  • Monitor verification status (polling or webhook)
  • Wait for verification-status: "checks-complete"
  • Monitor legal person for final decision
  • Confirm application-status: "accepted"

Need help?​