Create a company onboarding link using the API

Create a unique company onboarding link for each user with the API.

Unique links using the API

• Unique onboarding links are single-use. If you get an HTTP 500 Internal Server Error when submitting the onboarding form, it's because an onboarding was already finalized using that link. You need to generate a new link.
• The true purpose of the state parameter is to prevent Cross-Site Request Forgery (CSRF) and related attacks. Consider using it to your advantage. It includes your user's onboarding ID by default, so you can save this onboarding ID when generating the link.

1. Call the createCompanyAccountHolderOnboarding mutation.
2. Enter information for all required API fields for the account country, as noted in country requirements for company accounts.
   1. Start with accountInfo (account country and optional name).
   2. Add accountAdmin details (email, language, type of representation).
   3. Add the company object with business details and relatedIndividuals.
3. Include optional fields as needed for your use case (such as accountInfo.name or oAuthRedirectParameters).
4. Add optional messages to the success payload, either for validation or in case of rejection.

Deprecated mutation

The previous onboardCompanyAccountHolder mutation is deprecated.

Creating onboardings with the deprecated mutations stops on 30 September 2026; the deprecated mutations and queries are removed on 31 December 2026.

Use createCompanyAccountHolderOnboarding for all new integrations.

Pre-fill for French companies

For companies 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.

Mutation

Open in API Explorer

mutation CreateCompanyOnboarding {
  createCompanyAccountHolderOnboarding(
    input: {
      accountInfo: {
        country: ESP
      }
      accountAdmin: {
        email: "alberto.moreno@mimarca.io"
        preferredLanguage: es
        typeOfRepresentation: LegalRepresentative
      }
      company: {
        name: "MiMarca"
        businessActivity: Construction
        businessActivityDescription: "Historical restoration"
        registrationNumber: "123456789"
        monthlyPaymentVolume: Between10000And50000
        address: {
          addressLine1: "21 Barrio de San Roque"
          city: "Barcelona"
          country: "ESP"
          postalCode: "08005"
        }
        taxIdentificationNumber: "Y1234567Z"
        relatedIndividuals: [
          {
            type: LegalRepresentativeAndUltimateBeneficialOwner
            firstName: "Sofia"
            lastName: "Ramos"
            sex: Female
            birthInfo: {
              birthDate: "1990-03-03"
              country: "ESP"
              city: "Madrid"
            }
            address: {
              addressLine1: "1 Camino del Oceano"
              city: "Barcelona"
              country: "ESP"
              postalCode: "08005"
            }
            ultimateBeneficialOwner: {
              qualificationType: Ownership
              ownership: {
                type: Direct
                totalPercentage: 40
              }
            }
          }
        ]
      }
    }
  ) {
    ... on CreateCompanyAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
        }
      }
    }
  }
}

Payload

If you added validation or rejection messages, you'll see information such as the onboarding id as well as the current status Valid in the success payload.

{
  "data": {
    "createCompanyAccountHolderOnboarding": {
      "__typename": "CreateCompanyAccountHolderOnboardingSuccessPayload",
      "onboarding": {
        "id": "eda0ceec-0e20-4d1b-bbee-b3e3a4227c99",
        "statusInfo": {
          "status": "Valid"
        }
      }
    }
  }
}