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: creating the case, completing onboarding, and uploading documents. Refer to the France guide for the whole 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.

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 end 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 contribution	● 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, refer to 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, refer to 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:

Declare the UBOs of the company shareholder in shareholders[].company.company.relatedIndividuals.
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. Swan can create an onboarding with the status Invalid when a required field is missing. Get information about the onboarding, read the errors array, and fix the issue before finalization.

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, refer to the 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.

When all conditions are met, the case transitions to PendingInternalReview. For the full lifecycle and status transitions, refer to the 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"]
    }
  ]
}

Create a capital deposit case

Overview​

What's new​

Step 1: Prepare your data​

Field Requirements Legend

Find valid legal form codes​

Model UBOs across the ownership structure​

Step 2: Call the mutation​

Mutation​

Payload​

Step 3: Store IDs and check onboarding status​

Step 4: Complete onboarding and KYC​

Step 5: Upload required documents​

Query​

Payload​

Rejections​

Overview

What's new

Step 1: Prepare your data

Find valid legal form codes

Model UBOs across the ownership structure

Step 2: Call the mutation

Mutation

Payload

Step 3: Store IDs and check onboarding status

Step 4: Complete onboarding and KYC

Step 5: Upload required documents

Query

Payload

Rejections