Create a capital deposit case

Create a capital deposit case for a new company. One API call starts onboarding for the main company and all shareholders.

Multi-step process

This page covers the first part of a multi-step process:

1. Create the capital deposit case.
2. Complete company and shareholder onboarding.
3. Complete identity and account-holder verification.
4. Upload the required documents.

The mutation creates the case and the related onboardings. It doesn't complete onboarding, verification, document review, or capital transfers.

Refer to the Dashboard guide for the full operational process.

Overview

The createCapitalDeposit mutation is the new entry point for the capital deposit product, replacing the deprecated createCapitalDepositCase mutation.

A single call creates:

• One onboarding for the main company being formed.
• One onboarding for each company shareholder, if any.
• One onboarding for each individual shareholder, if any.

Provide all shareholder data in the initial request. This mutation is designed for one complete submission. You can update a company or individual onboarding to make corrections, but updates aren't the intended path for building a case incrementally.

Partner experience

The response includes an onboardingUrl for the future company and for each shareholder.

Expose the relevant URL through your partner experience so that the company administrator and shareholders can complete their onboarding. Store each onboarding ID so that you can monitor progress and retrieve validation errors.

A successful createCapitalDeposit response doesn't mean that onboarding or KYC is complete. Continue monitoring each onboarding and account-holder status.

What's new

createCapitalDeposit replaces the monolithic onboardingInfo block from createCapitalDepositCase with structured, per-entity inputs aligned with the standard Swan onboarding format.

Deprecated (createCapitalDepositCase)	New (createCapitalDeposit)
companyShareholders[].onboardingInfo	shareholders[].company with accountInfo, accountAdmin, company, and oAuthRedirectParameters
individualShareholders[].onboardingInfo	shareholders[].individual with accountInfo, accountAdmin, and oAuthRedirectParameters
onboardingInfo.accountName	accountInfo.name
representatives	company.relatedIndividuals[] with the type LegalRepresentative
individualUltimateBeneficialOwners	company.relatedIndividuals[] with the type UltimateBeneficialOwner
direct and indirect booleans	ownership.type (Direct or Indirect) and ownership.totalPercentage
language	accountAdmin.preferredLanguage

The mutation accepts three top-level fields:

createCapitalDeposit(input: {
  acquisitionChannel: ...     # How you acquired the user
  mainCompany: { ... }        # The company being incorporated
  shareholders: [ ... ]       # One entry per shareholder
})

Each entry in shareholders must contain exactly one of company or individual:

{ company: { ... } }      # Company shareholder
{ individual: { ... } }   # Individual shareholder

Step 1: Prepare your data

Collect the following information for each entity before calling the mutation.

Field Requirements Legend

● REQ Required: Must be completed.

◐ CND Conditional: Required only in specific situations.

○ OPT Optional: Isn't required; may have a default value.

⊘ N/A Not applicable: Not used.

On this page, ● REQ means the mutation rejects the call without the field. ◐ CND means the mutation accepts the call without the field, but Swan sets the onboarding status to Invalid until you provide it. Query statusInfo.errors on each onboarding before finalizing it, then update the onboarding with the missing values.

For every account, the account name is optional. If you don't provide one, Swan uses dépôt de capital — <holder name> by default.

Main company

Data to prepare	Requirement	API field
Company name	● REQ	mainCompany.company.name
Trade name	○ OPT	mainCompany.company.tradeName
Legal form code	◐ CND	mainCompany.company.legalFormCode
Registration number	○ OPT	mainCompany.company.registrationNumber
Registered address	◐ CND	mainCompany.company.address
Business activity	◐ CND	mainCompany.company.businessActivity, mainCompany.company.businessActivityCode, mainCompany.company.businessActivityDescription
Account admin	● REQ	mainCompany.accountAdmin
UBOs and legal representatives	◐ CND	mainCompany.company.relatedIndividuals
Account name	○ OPT	mainCompany.accountInfo.name
Redirect URL	● REQ	mainCompany.oAuthRedirectParameters.redirectUrl

The main company isn't incorporated yet, so its registration number is optional.

Each company shareholder

Data to prepare	Requirement	API field
Capital deposit amount	● REQ	shareholders[].company.capitalDepositAmount
Company name	● REQ	shareholders[].company.company.name
Trade name	○ OPT	shareholders[].company.company.tradeName
Legal form code	◐ CND	shareholders[].company.company.legalFormCode
Registration number	◐ CND	shareholders[].company.company.registrationNumber
Registered address	◐ CND	shareholders[].company.company.address
Business activity	◐ CND	shareholders[].company.company.businessActivity, shareholders[].company.company.businessActivityCode, shareholders[].company.company.businessActivityDescription
Account admin	● REQ	shareholders[].company.accountAdmin
UBOs and legal representatives	◐ CND	shareholders[].company.company.relatedIndividuals
Account name	○ OPT	shareholders[].company.accountInfo.name
Redirect URL	● REQ	shareholders[].company.oAuthRedirectParameters.redirectUrl

Company shareholders are registered legal entities, so provide their registration number.

Pre-fill for French companies

For company shareholders registered in France, use the companyInfoRegistryData query with the company's registration number to retrieve data from the National Business Register (RNE). Pass the results to the mutation to pre-fill company fields.

For complete field-level requirements and required-document rules, see company onboarding fields.

Each individual shareholder

Data to prepare	Requirement	API field
Capital contribution	● REQ	shareholders[].individual.capitalDepositAmount
First and last name	● REQ	shareholders[].individual.accountAdmin.firstName and lastName
Date and place of birth	● REQ	shareholders[].individual.accountAdmin.birthInfo
Nationality	● REQ	shareholders[].individual.accountAdmin.nationality
Address	◐ CND	shareholders[].individual.accountAdmin.address
Employment status and income	◐ CND	shareholders[].individual.accountAdmin.employmentStatus and monthlyIncome
FATCA information	◐ CND	shareholders[].individual.accountAdmin.unitedStatesTaxInfo
Account name	○ OPT	shareholders[].individual.accountInfo.name
Redirect URL	● REQ	shareholders[].individual.oAuthRedirectParameters.redirectUrl

For complete field-level requirements and required-document rules, see individual onboarding fields.

Find valid legal form codes

Use the legalForms query to get all valid legal form codes for a country, with localized names and abbreviations.

Open in API Explorer

query GetLegalForms {
  legalForms(country: "FRA") {
    code
    country
    localName
    localAbbreviation
  }
}

Model UBOs across the ownership structure

When a company is a shareholder of the company being incorporated, declare UBOs at both company levels:

1. Declare the UBOs of the company shareholder in shareholders[].company.company.relatedIndividuals.
2. Declare the individuals who ultimately own the main company, directly or through a company shareholder, in mainCompany.company.relatedIndividuals.

The same individual can appear in both places, but calculate the ownership percentage relative to the entity being described.

MyBrand
├── 50% owned directly by Henri Dupont
└── 50% owned by MyBrand Company Shareholder
    └── 100% owned by Jules Fleury

Individual	Entity	Relationship	Percentage
Henri Dupont	MyBrand	Direct UBO	50%
Jules Fleury	MyBrand	Indirect UBO through the company shareholder	50%
Jules Fleury	MyBrand Company Shareholder	Direct UBO	100%

The percentage in the main company UBO entry is the person's effective ownership of the main company. It's not necessarily the percentage they hold in the intermediate company. For example, if an intermediate company owns 50% of the main company and an individual owns 60% of that intermediate company, the individual's indirect ownership of the main company is 30%.

A legal representative isn't automatically a UBO. Choose the type that matches the individual's roles:

• UltimateBeneficialOwner for a UBO only.
• LegalRepresentative for a legal representative only.
• LegalRepresentativeAndUltimateBeneficialOwner when the same individual has both roles.

relatedCompanies doesn't model ownership

Only use relatedCompanies when a legal entity acts as the legal representative of another company. Represent shareholder ownership through the shareholder company and its relatedIndividuals.

Step 2: Call the mutation

The following example shows a case with one company shareholder and one individual shareholder.

Mutation

Open in API Explorer

mutation CreateCapitalDeposit {
  createCapitalDeposit(
    input: {
      acquisitionChannel: OutboundAccountingFirm

      mainCompany: {
        accountInfo: {
          name: "dépôt de capital — MyBrand"
        }

        accountAdmin: {
          firstName: "Jules"
          lastName: "Fleury"
          email: "bonjour@mybrand.fr"
          preferredLanguage: fr
          nationality: "FRA"
          typeOfRepresentation: LegalRepresentative
          birthInfo: {
            birthDate: "1990-06-01"
            city: "Paris"
            country: "FRA"
            postalCode: "75007"
          }
          address: {
            addressLine1: "10 rue Duris"
            addressLine2: "Bâtiment A"
            country: "FRA"
            city: "Paris"
            postalCode: "75020"
            state: "Ile de France"
          }
        }

        company: {
          name: "MyBrand"
          legalFormCode: "6CHY"
          tradeName: "MB"
          address: {
            addressLine1: "168 Rue Saint-Maur"
            addressLine2: "Bâtiment A"
            country: "FRA"
            city: "Paris"
            postalCode: "75011"
            state: "Ile de France"
          }
          businessActivity: AccommodationAndFoodService
          businessActivityDescription: "Establishment that serves traditional French cuisine."
          monthlyPaymentVolume: Between50000And100000
          regulatoryClassification: NonFinancialActive
          relatedIndividuals: [
            {
              # Henri Dupont - direct UBO holding 50%
              type: UltimateBeneficialOwner
              firstName: "Henri"
              lastName: "Dupont"
              sex: Male
              nationality: "FRA"
              birthInfo: {
                birthDate: "1988-02-25"
                city: "Paris"
                country: "FRA"
                postalCode: "75008"
              }
              address: {
                addressLine1: "24 Rue Saint-Ambroise"
                addressLine2: "Bâtiment A"
                country: "FRA"
                city: "Paris"
                postalCode: "75011"
                state: "Ile de France"
              }
              unitedStatesTaxInfo: {
                isUnitedStatesPerson: false
              }
              ultimateBeneficialOwner: {
                qualificationType: Ownership
                ownership: {
                  type: Direct
                  totalPercentage: 50
                }
              }
            }
            {
              # Jules Fleury - indirect UBO holding 50% and legal representative
              type: LegalRepresentativeAndUltimateBeneficialOwner
              firstName: "Jules"
              lastName: "Fleury"
              sex: Male
              nationality: "FRA"
              birthInfo: {
                birthDate: "1990-06-01"
                city: "Paris"
                country: "FRA"
                postalCode: "75007"
              }
              address: {
                addressLine1: "10 rue Duris"
                addressLine2: "Bâtiment A"
                country: "FRA"
                city: "Paris"
                postalCode: "75020"
                state: "Ile de France"
              }
              unitedStatesTaxInfo: {
                isUnitedStatesPerson: false
              }
              ultimateBeneficialOwner: {
                qualificationType: Ownership
                ownership: {
                  type: Indirect
                  totalPercentage: 50
                }
              }
              legalRepresentative: {
                roles: ["President"]
              }
            }
          ]
        }

        oAuthRedirectParameters: {
          redirectUrl: "https://www.mybrand.fr"
        }
      }

      shareholders: [
        {
          company: {
            capitalDepositAmount: {
              value: "500"
              currency: "EUR"
            }

            accountInfo: {
              name: "dépôt de capital — MyBrand Company Shareholder"
            }

            accountAdmin: {
              firstName: "Jules"
              lastName: "Fleury"
              email: "companyshareholder@mybrand.fr"
              preferredLanguage: fr
              nationality: "FRA"
              typeOfRepresentation: LegalRepresentative
              birthInfo: {
                birthDate: "1990-06-01"
                city: "Paris"
                country: "FRA"
                postalCode: "75007"
              }
              address: {
                addressLine1: "10 rue Duris"
                addressLine2: "Bâtiment A"
                country: "FRA"
                city: "Paris"
                postalCode: "75020"
                state: "Ile de France"
              }
            }

            company: {
              name: "MyBrand Company Shareholder"
              legalFormCode: "6CHY"
              tradeName: "MyBrand CS"
              address: {
                addressLine1: "91 rue du Faubourg Saint-Honoré"
                addressLine2: "Bâtiment A"
                country: "FRA"
                city: "Paris"
                postalCode: "75008"
                state: "Ile de France"
              }
              businessActivity: AccommodationAndFoodService
              businessActivityDescription: "Establishment that serves traditional French cuisine."
              monthlyPaymentVolume: Between50000And100000
              regulatoryClassification: NonFinancialActive
              registrationNumber: "853827103"
              taxIdentificationNumber: "853827103"
              vatNumber: "FR90853827103"
              relatedIndividuals: [
                {
                  # Jules Fleury - 100% direct UBO and legal representative
                  type: LegalRepresentativeAndUltimateBeneficialOwner
                  firstName: "Jules"
                  lastName: "Fleury"
                  sex: Male
                  nationality: "FRA"
                  birthInfo: {
                    birthDate: "1990-06-01"
                    city: "Paris"
                    country: "FRA"
                    postalCode: "75007"
                  }
                  address: {
                    addressLine1: "10 rue Duris"
                    addressLine2: "Bâtiment A"
                    country: "FRA"
                    city: "Paris"
                    postalCode: "75020"
                    state: "Ile de France"
                  }
                  unitedStatesTaxInfo: {
                    isUnitedStatesPerson: false
                  }
                  ultimateBeneficialOwner: {
                    qualificationType: Ownership
                    ownership: {
                      type: Direct
                      totalPercentage: 100
                    }
                  }
                  legalRepresentative: {
                    roles: ["President"]
                  }
                }
              ]
            }

            oAuthRedirectParameters: {
              redirectUrl: "https://www.mybrand.fr"
            }
          }
        }

        {
          individual: {
            capitalDepositAmount: {
              value: "500"
              currency: "EUR"
            }

            accountInfo: {
              name: "dépôt de capital — Henri Dupont"
            }

            accountAdmin: {
              firstName: "Henri"
              lastName: "Dupont"
              email: "henri.dupont@mybrand.fr"
              preferredLanguage: fr
              nationality: "FRA"
              employmentStatus: Entrepreneur
              monthlyIncome: MoreThan4500
              birthInfo: {
                birthDate: "1988-02-25"
                city: "Paris"
                country: "FRA"
                postalCode: "75008"
              }
              address: {
                addressLine1: "24 Rue Saint-Ambroise"
                addressLine2: "Bâtiment A"
                country: "FRA"
                city: "Paris"
                postalCode: "75011"
                state: "Ile de France"
              }
              # Required to finalize an individual onboarding
              unitedStatesTaxInfo: {
                isUnitedStatesPerson: false
              }
            }

            oAuthRedirectParameters: {
              redirectUrl: "https://www.mybrand.fr"
            }
          }
        }
      ]
    }
  ) {
    __typename

    ... on CreateCapitalDepositSuccessPayload {
      capitalDepositCase {
        id

        statusInfo {
          status
        }

        totalCapitalDepositAmount {
          currency
          value
        }

        companyOnboarding {
          id
          onboardingUrl
          statusInfo {
            status
            validationVersion
            ... on OnboardingInvalidStatusInfo {
              errors {
                details
                errors
                field
              }
            }
          }
        }

        shareholders {
          id
          status
          onboarding {
            id
            onboardingUrl
            statusInfo {
              status
              validationVersion
              ... on OnboardingInvalidStatusInfo {
                errors {
                  details
                  errors
                  field
                }
              }
            }
          }
        }
      }
    }

    ... on CapitalDepositShareholdersEmptyRejection {
      message
    }

    ... on CapitalDepositMainCompanyOnboardingRejection {
      message
      fields {
        message
        path
      }
    }

    ... on CapitalDepositShareholderOnboardingRejection {
      message
      fields {
        message
        path
      }
    }
  }
}

Payload

The success payload returns the case, the main company onboarding, and one entry per shareholder, in the order you sent them. The highlighted lines are the IDs to store: the case (line 6), the main company onboarding (line 15), and each shareholder with its onboarding (lines 24, 27, 36, and 39). Every onboarding in this example is Valid, so no errors array is returned.

{
  "data": {
    "createCapitalDeposit": {
      "__typename": "CreateCapitalDepositSuccessPayload",
      "capitalDepositCase": {
        "id": "a4c9da36-56e1-4ed8-b0a1-2c9f3d7e8b12",
        "statusInfo": {
          "status": "WaitingForInitialRequirements"
        },
        "totalCapitalDepositAmount": {
          "currency": "EUR",
          "value": "1000"
        },
        "companyOnboarding": {
          "id": "3f9c2b1e-7d4a-4e8f-9a6b-1c2d3e4f5a60",
          "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/3f9c2b1e-7d4a-4e8f-9a6b-1c2d3e4f5a60?lang=fr",
          "statusInfo": {
            "status": "Valid",
            "validationVersion": "V2"
          }
        },
        "shareholders": [
          {
            "id": "8b1e6f2a-0c3d-4a5b-8e9f-6a7b8c9d0e11",
            "status": "PendingOnboarding",
            "onboarding": {
              "id": "c7d2e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e22",
              "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/c7d2e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e22?lang=fr",
              "statusInfo": {
                "status": "Valid",
                "validationVersion": "V2"
              }
            }
          },
          {
            "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f33",
            "status": "PendingOnboarding",
            "onboarding": {
              "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a44",
              "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a44?lang=fr",
              "statusInfo": {
                "status": "Valid",
                "validationVersion": "V2"
              }
            }
          }
        ]
      }
    }
  }
}

Step 3: Store IDs and check onboarding status

From a successful response, store:

• capitalDepositCase.id: your reference for the full case.
• capitalDepositCase.companyOnboarding.id: to track the main company onboarding. Also store onboardingUrl to redirect your user, unless your integration is API-only.
• shareholders[].onboarding.id: to track each shareholder onboarding. Also store each onboardingUrl, unless your integration is API-only.

A successful mutation doesn't mean every onboarding is ready to be finalized.

Check every onboarding status

Always check statusInfo.status on companyOnboarding and on each shareholders[].onboarding.

Completing onboarding doesn't guarantee that account holder verification is complete. Swan may request additional information during KYC, so continue monitoring the account holder status after you finalize the onboarding.

Swan can create an onboarding with the status Invalid when a required field is missing.

Refer to the Get information about the onboarding guide, read the errors array, and fix the issue before you finalize the onboarding.

Example of a case created with an invalid onboarding:

{
  "capitalDepositCase": {
    "statusInfo": { "status": "WaitingForInitialRequirements" },
    "companyOnboarding": {
      "statusInfo": {
        "status": "Invalid",
        "validationVersion": "V2",
        "errors": [
          {
            "field": "company.legalFormCode",
            "details": "Invalid input: expected string, received null"
          }
        ]
      }
    }
  }
}

Required documents per onboarding

The documents needed to complete an onboarding depend on the entity and context. Before asking your user to complete the flow, get a list of required onboarding documents.

Step 4: Complete onboarding and KYC

After your users finalize their onboardings, the KYC process for each entity begins with the identification of each account admin (the first account membership, with legalRepresentative: true).

Step 5: Upload required documents

For the list of required documents by stakeholder, who provides each one, and where it's attached, see capital deposits overview.

After you create the case, the capital deposit case status is WaitingForInitialRequirements. The case stays in this status until all of the following are complete:

• All required capital deposit documents are Uploaded.
• All shareholders passed KYC verification and reached the status CapitalTransferred.
• The main company onboarding is completed.

Document upload and KYC happen in parallel, so you don't need to wait for shareholders to finish their onboarding. Start uploading as soon as the documents are available.

If Swan refuses a document, review its refusal reason and upload a corrected version. The document status returns to Uploaded while Swan reviews the replacement. Refer to Upload required documents for the document upload and replacement process.

When all conditions are met, the case transitions to PendingInternalReview. For the full lifecycle and status transitions, see capital deposits overview.

The case and each shareholder have a documents array with pre-assigned document IDs and types. Query the case for the document IDs. Then upload each document using the two-step signed URL flow.

Query

Open in API Explorer

query GetCapitalDepositDocuments {
  capitalDepositCase(id: "$YOUR_CAPITALDEPOSITCASE_ID") {
    documents {
      id
      type
      statusInfo {
        status
      }
    }
    shareholders {
      id
      documents {
        id
        type
        statusInfo {
          status
        }
      }
    }
  }
}

Payload

Each document placeholder is created with the status Pending. The highlighted lines are the document IDs to store: case documents (lines 6, 13, and 20) and the individual shareholder's proof of address (line 36). The company shareholder has an empty documents array because Swan collects its registry extract during onboarding.

{
  "data": {
    "capitalDepositCase": {
      "documents": [
        {
          "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01",
          "type": "ArticlesOfIncorporation",
          "statusInfo": {
            "status": "Pending"
          }
        },
        {
          "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d02",
          "type": "CompanyLeaseAgreement",
          "statusInfo": {
            "status": "Pending"
          }
        },
        {
          "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e03",
          "type": "PowerOfAttorney",
          "statusInfo": {
            "status": "Pending"
          }
        }
      ],
      "shareholders": [
        {
          "id": "8b1e6f2a-0c3d-4a5b-8e9f-6a7b8c9d0e11",
          "documents": []
        },
        {
          "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f33",
          "documents": [
            {
              "id": "3d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f04",
              "type": "ProofOfIndividualAddress",
              "statusInfo": {
                "status": "Pending"
              }
            }
          ]
        }
      ]
    }
  }
}

Rejections

Rejection type	Meaning
CapitalDepositShareholdersEmptyRejection	No shareholder was provided.
CapitalDepositMainCompanyOnboardingRejection	The main company onboarding data is invalid.
CapitalDepositShareholderOnboardingRejection	A shareholder onboarding entry is invalid.

The fields array in each rejection identifies the exact field and path causing the error:

{
  "__typename": "CapitalDepositShareholderOnboardingRejection",
  "fields": [
    {
      "message": "Legal form code is invalid.",
      "path": ["shareholders", "0", "company", "company", "legalFormCode"]
    }
  ]
}