> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to submit a UBO Declaration

## Introduction

This how-to guide will show you how to successfully submit a UBO Declaration for validation by Mangopay.

<Info>
  **Prerequisites**

  * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
  * A legal Owner user whose `LegalPersonType` is `BUSINESS` or `PARTNERSHIP` and for whom you have submitted all the necessary KYC Documents (see <a href="/guides/users/verification/documents/submission/how-to">How to submit a KYC Document</a>).
</Info>

The UBO Declaration object allows you to submit information concerning the beneficial owners of a legal user. Find out more about the process in the <a href="/guides/users/verification/beneficial-owners">Beneficial owners</a> article.

<Note>
  **Best practice - Submit KYC Documents before UBO Declaration**

  Because the information in the UBO Declaration is compared with the verification documents, it is necessary to submit all the required documents first before submitting the UBO Declaration.
</Note>

<a href="/guides/users/verification/documents/submission/how-to">How to submit a KYC Document →</a>

## Test data

You can simulate the acceptance or refusal of a UBO Declaration in Sandbox. To do so, when you create the first UBO (Step 2 below), set the `FirstName` to the relevant (case-sensitive) value to produce the desired outcome after submission (Step 4):

<table>
  <thead>
    <tr>
      <th class="header">
        First UBO `FirstName` value
      </th>

      <th class="header">
        Final `Status`
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `AcceptUBO`
      </td>

      <td class="table-content">
        `VALIDATED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `RefuseUBO`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `IncompleteUBO`
      </td>

      <td class="table-content">
        `INCOMPLETE`
      </td>
    </tr>
  </tbody>
</table>

## 1. Create the UBO Declaration

Create the UBO Declaration with the `UserId`.

> [**POST** /v2.01/\{ClientId}/users/\{UserId}/kyc/ubodeclarations](/api-reference/ubo-declarations/create-ubo-declaration)

<CodeGroup>
  ```php PHP theme={null}
  <?php 

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $userId = '199463368';

      $response = $api->UboDeclarations->Create($userId);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }  
  ```

  ```javascript NodeJS   theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk')
  const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
  })

  let myUser = {
      Id: 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'
  }

  const createUboDeclaration = async (userId) => {
    return await mangopay.UboDeclarations.create(userId)
      .then((response) => {
        console.info(response)
        return response
      })
      .catch((err) => {
        console.log(err)
        return false
      })
  }

  createUboDeclaration(myUser.Id)  
  ```

  ```ruby Ruby   theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def createUboDeclaration(legalUserId)
      begin
          response = MangoPay::UboDeclaration.create(legalUserId)
          puts response
          return response
      rescue MangoPay::ResponseError => error
          puts "Failed to create UBO Declaration: #{error.message}"
          puts "Error details: #{error.details}"
          return false
      end
  end

  myLegalUser = {
      Id: '194338122'
  }

  createUboDeclaration(myLegalUser[:Id])  
  ```

  ```java Java   theme={null}
  import com.mangopay.MangoPayApi;
  import com.mangopay.entities.UboDeclaration;
  import com.mangopay.entities.UserLegal;

  import java.lang.reflect.Field;

  public class CreateUBODeclaraction {
       public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          UserLegal myUser = mangopay.getUserApi().getLegal("user_m_01HQK53VP687RBSH2Q5TJZRR3S");
      
          UboDeclaration createUboDeclaration = mangopay.getUboDeclarationApi().create(myUser.getId());

          System.out.println(String.format("id: %s", createUboDeclaration.getId()));
          printObjectFields(createUboDeclaration);
      }

      private static void printObjectFields(Object obj) {
          Class<?> objClass = obj.getClass();
          Field[] fields = objClass.getDeclaredFields();
          for (Field field : fields) {
              field.setAccessible(true);
              try {
                  Object value = field.get(obj);
                  System.out.println(field.getName() + ": " + value);
              } catch (IllegalAccessException e) {
                  e.printStackTrace();
              }
          }
      }
  }  
  ```

  ```python Python   theme={null}
  from pprint import pprint
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import UboDeclaration, LegalUser

  legal_user = LegalUser(
      id = '210760575'
  )

  ubo_declaration = UboDeclaration(user=legal_user)
  create_ubo_declaration = ubo_declaration.save()

  pprint(create_ubo_declaration)  
  ```
</CodeGroup>

The response shows the `Status` “CREATED” and contains an `Id`, which is the unique identifier of the UBO Declaration object. You need to save this for the next step.

<hr />

## 2. Create the first UBO

With the `Id` of the UBO Declaration as the `UboDeclarationId` path parameter, create the first UBO, entering the required information. In Sandbox, set the `FirstName` to the desired test outcome, for example, `AcceptUBO`.

> [**POST** /v2.01/\{ClientId}/users/\{UserId}/kyc/ubodeclarations/\{UboDeclarationId}/ubos](/api-reference/ubo-declarations/create-ubo)

<CodeGroup>
  ```json REST   theme={null}
  {
      "FirstName": "AcceptUBO",
      "LastName": "Effertz",
      "Birthday": 652117514,
      "Nationality": "FR",
      "Address": {
          "AddressLine1": "804 Hane Mountains",
          "AddressLine2": "Adriel Overpass",
          "City": "Paris",
          "Region": "Île-de-France",
          "PostalCode": "75001",
          "Country": "FR"
      },
      "Birthplace": {
          "City": "Paris",
          "Country": "FR"
      }
  }  
  ```

  ```php PHP theme={null}
  <?php 

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $userId = '198557165';
      $uboDeclarationId = '198692872';

      $ubo = new \MangoPay\Ubo();

      $address = new \MangoPay\Address();
      $address->AddressLine1 = 'Address line 1';
      $address->AddressLine2 = 'Address line 2';
      $address->City = 'Paris';
      $address->Country = 'FR';
      $address->PostalCode = '75000';
      $address->Region = 'Region';

      $ubo->Address = $address;
      $ubo->FirstName = 'AcceptUBO';
      $ubo->LastName = 'Doe';
      $ubo->Nationality = 'FR';
      $ubo->Birthday = mktime(0, 0, 0, 12, 21, 1975); 

      $Birthplace = new \MangoPay\Birthplace();
      $Birthplace->City = 'Paris';
      $Birthplace->Country = 'FR';

      $ubo->Birthplace = $Birthplace;

      $response = $api->UboDeclarations->CreateUbo($userId, $uboDeclarationId, $ubo);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }  
  ```

  ```javascript NodeJS   theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk')
  const mangopay = new mangopayInstance({
    clientId: 'your-client-id',
    clientApiKey: 'your-api-key',
  })

  let myUser = {
    Id: '170853400',
  }

  let myUboDeclaration = {
    Id: '180932134',
  }

  let myUbo = {
    FirstName: 'AcceptUBO',
    LastName: 'Smith',
    Address: {
      AddressLine1: '669 Ratke Forge',
      AddressLine2: 'Schamberger Walk',
      City: 'Paris',
      Region: 'Île-de-France',
      PostalCode: '75001',
      Country: 'FR',
    },
    Nationality: 'FR',
    Birthday: 652117514,
    Birthplace: {
      City: 'Paris',
      Country: 'FR',
    },
  }

  const createUbo = async (userId, uboDeclarationId, ubo) => {
    return await mangopay.UboDeclarations.createUbo(userId, uboDeclarationId, ubo)
      .then((response) => {
        console.info(response)
        return response
      })
      .catch((err) => {
        console.log(err)
        return false
      })
  }

  createUbo(myUser.Id, myUboDeclaration.Id, myUbo)  
  ```

  ```ruby Ruby   theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def createUbo(legalUserId, uboDeclarationId, uboObject)
      begin
          response = MangoPay::Ubo.create(legalUserId, uboDeclarationId, uboObject)
          puts response
          return response
      rescue MangoPay::ResponseError => error
          puts "Failed to create UBO: #{error.message}"
          puts "Error details: #{error.details}"
          return false
      end
  end

  myLegalUser = {
      Id: '194338122'
  }

  myUboDeclaration = {
      Id: '194511216'
  }

  myUbo = {
      FirstName: 'AcceptUBO',
      LastName: 'Smith',
      Address: {
              AddressLine1: '669 Ratke Forge',
              AddressLine2: 'Schamberger Walk',
              City: 'Paris',
              Region: 'Île-de-France',
              PostalCode: '75001',
              Country: 'FR'
          },
      Nationality: 'FR',
      Birthday: 652117514,
      Birthplace: {
          City: 'Paris',
          Country: 'FR'
      }
  }

  createUbo(myLegalUser[:Id], myUboDeclaration[:Id], myUbo)  
  ```

  ```java Java   theme={null}
  import com.mangopay.MangoPayApi;
  import com.mangopay.core.Address;
  import com.mangopay.core.enumerations.CountryIso;
  import com.mangopay.entities.Birthplace;
  import com.mangopay.entities.Ubo;
  import com.mangopay.entities.UboDeclaration;
  import com.mangopay.entities.UserLegal;

  import java.lang.reflect.Field;

  public class CreateUBO {
       public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          UserLegal myUser = mangopay.getUserApi().getLegal("user_m_01HQK53VP687RBSH2Q5TJZRR3S");
      
          UboDeclaration myUboDeclaration = mangopay.getUboDeclarationApi().get("ubo_m_01HRYRPZDB3KXF0QZ6QZ5C95A8");

          Ubo myUbo = new Ubo();

          Address address = new Address();
          Birthplace birthplace = new Birthplace();

          address.setAddressLine1(myUser.getHeadquartersAddress().getAddressLine1());
          address.setAddressLine2(myUser.getHeadquartersAddress().getAddressLine2());
          address.setCity(myUser.getHeadquartersAddress().getCity());
          address.setCountry(myUser.getHeadquartersAddress().getCountry());
          address.setRegion(myUser.getHeadquartersAddress().getRegion());
          address.setPostalCode(myUser.getHeadquartersAddress().getPostalCode());

          birthplace.setCity("Paris");
          birthplace.setCountry(CountryIso.FR);

          myUbo.setFirstName(myUser.getLegalRepresentativeFirstName());
          myUbo.setLastName(myUser.getLegalRepresentativeLastName());
          myUbo.setAddress(address);
          myUbo.setNationality(CountryIso.FR);
          myUbo.setBirthday(336879600);
          myUbo.setBirthplace(birthplace);
          myUbo.setActive(true);
          myUbo.setTag("create-ubo-java");

          Ubo createMyUbo = mangopay.getUboDeclarationApi().createUbo(myUser.getId(), myUboDeclaration.getId(), myUbo);
          
          System.out.println(String.format("id: %s", createMyUbo.getId()));
          printObjectFields(createMyUbo);
      }

          private static void printObjectFields(Object obj) {
          Class<?> objClass = obj.getClass();
          Field[] fields = objClass.getDeclaredFields();
          for (Field field : fields) {
              field.setAccessible(true);
              try {
                  Object value = field.get(obj);
                  if (value instanceof Address
                      || value instanceof Birthplace) {
                      System.out.println(field.getName() + ": ");
                      printObjectFields(value); 
                  } else {
                      System.out.println(field.getName() + ": " + value);
                  }
              } catch (IllegalAccessException e) {
                  e.printStackTrace();
              }
          }
      }
  }  
  ```

  ```python Python   theme={null}
  from pprint import pprint
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import Ubo, UboDeclaration, LegalUser
  from mangopay.utils import Address, Birthplace

  legal_user = LegalUser(
      id = '210760575'
  )

  user_ubo_declaration = UboDeclaration(
      id = '210863422'
  )

  user_ubo = Ubo(
      first_name = “Ellie”, 
      last_name = “Adams”, 
      address = Address(
          address_line_1 = ’23 Brook Road’,
          city = 'London',
          postal_code = 'NE1 0AA',
          country = 'GB',
      ),
      nationality = 'GB',
      birthday = 336672000,
      birthplace = Birthplace(
          city = 'London',
          country = 'GB'
      ),
      user = legal_user,
      ubo_declaration = user_ubo_declaration,
      isActive = True
  )

  create_ubo = user_ubo.save()

  pprint(create_ubo)
    
  ```
</CodeGroup>

<hr />

## 3. Create additional UBOs as needed

Repeat Step 2 as many times as necessary. Your UBO Declaration can contain a minimum of 1 and a maximum of 15 UBOs.

<hr />

## 4. Submit the UBO Declaration

Once all UBOs are created and correctly declared, submit the declaration for review by Mangopay’s teams by changing the `Status` from `CREATED` to `VALIDATION_ASKED`.

> [**PUT** /v2.01/\{ClientId}/users/\{UserId}/kyc/ubodeclarations/\{UboDeclarationId}](/api-reference/ubo-declarations/submit-ubo-declaration)

<CodeGroup>
  ```json REST   theme={null}
  {
      "Status": "VALIDATION_ASKED",
  }  
  ```

  ```php PHP theme={null}
  <?php 

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $userId = '199385330';
      $uboDeclarationId = '199461371';

      $response = $api->UboDeclarations->SubmitForValidation($userId, $uboDeclarationId);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }  
  ```

  ```javascript NodeJS   theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk')
  const mangopay = new mangopayInstance({
    clientId: 'your-mangopay-client-id',
    clientApiKey: 'your-mangopay-api-key',
  })

  let myUser = {
    Id: '170853400',
  }

  let myUboDeclaration = {
    Id: '180932134',
    Status: 'VALIDATION_ASKED',
  }

  const updateUboDeclaration = async (userId, uboDeclaration) => {
    return await mangopay.UboDeclarations.update(userId, uboDeclaration)
      .then((response) => {
        console.info(response)
        return response
      })
      .catch((err) => {
        console.log(err)
        return false
      })
  }

  updateUboDeclaration(myUser.Id, myUboDeclaration)  
  ```

  ```ruby Ruby   theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def submitUboDeclaration(user_id, ubo_declaration_id, params)
      begin
          response = MangoPay::UboDeclaration.update(user_id, ubo_declaration_id, params)
          puts response
          return response
      rescue MangoPay::ResponseError => error
          puts "Failed to create UBO: #{error.message}"
          puts "Error details: #{error.details}"
          return false
      end
  end

  my_user = {
      Id: 'user_m_01J2BGH2PGWC4NNWGADT75ATB6'
  }

  my_ubo_declaration = {
      Id: 'ubo_m_01J29G0RXSSJXG34ZSPHRE955C'
  }

  params = {
      'Status' => 'VALIDATION_ASKED'
  }

  submitUboDeclaration(my_user[:Id], my_ubo_declaration[:Id], params) 

  ```

  ```java Java   theme={null}
  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;
  import com.mangopay.MangoPayApi;
  import com.mangopay.entities.UboDeclaration;
  import com.mangopay.entities.UserLegal;

  public class SubmitUBODeclaraction {
       public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          UboDeclaration uboDeclaration = mangopay.getUboDeclarationApi().get("ubo_m_01HRYRPZDB3KXF0QZ6QZ5C95A8");
          UserLegal myUser = mangopay.getUserApi().getLegal("user_m_01HQK53VP687RBSH2Q5TJZRR3S");
      
          UboDeclaration submitUboDeclaration = mangopay.getUboDeclarationApi().submitForValidation(myUser.getId(), uboDeclaration.getId());

          Gson prettyPrint = new GsonBuilder().setPrettyPrinting().create();
          String prettyJson = prettyPrint.toJson(submitUboDeclaration);

          System.out.println(prettyJson);
      }
  }
  ```

  ```python Python   theme={null}
  from pprint import pprint
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import UboDeclaration, LegalUser

  legal_user = LegalUser(
      id = '211158266'  
  )

  ubo_declaration = UboDeclaration(
      id = '211651591', 
      user = legal_user,
      status = 'VALIDATION_ASKED'
  )

  submit_ubo_declaration = ubo_declaration.save()

  pprint(submit_ubo_declaration)  
  ```
</CodeGroup>

<hr />

## 5. Set up relevant hooks (recommended)

There are dedicated hooks to provide notifications of the outcome of the review by Mangopay:

* `UBO_DECLARATION_VALIDATED`, notifying that the UBO Declaration status has changed to `VALIDATED`.
* `UBO_DECLARATION_REFUSED`, notifying that the UBO Declaration status has changed to `REFUSED`.
* `UBO_DECLARATION_INCOMPLETE`, notifying that the UBO Declaration status has changed to `INCOMPLETE`.

<Note>
  **Note - Only `INCOMPLETE` declarations can be reused**

  UBO Declarations can be resubmitted or not depending on their status:

  * `REFUSED` - The object can’t be re-submitted. You need to create a new declaration.
  * `INCOMPLETE` - The object can be modified and re-submitted.\
    For more information about why the declaration wasn’t validated, see the `Reason` and `Message` parameters returned by the <a href="/api-reference/ubo-declarations/view-ubo-declaration">View a UBO Declaration</a> endpoint.
</Note>

<hr />

## 7. If incomplete, take any remedial action

If the response from Mangopay is that the UBO Declaration is `INCOMPLETE`, check the [View a UBO Declaration](/api-reference/ubo-declarations/view-ubo-declaration) endpoint for information on why.

Take the necessary steps indicated by Mangopay in the `Reason` and `Message` parameters.

```json API Response example theme={null}
{
   "Id": "160691001",
   "UserId": "160686549",
   "CreationDate": 1674491433,
   "ProcessedDate": null,
   "Status": "INCOMPLETE",
   "Reason": "SHAREHOLDERS_DECLARATION_NEEDED",
   "Message": null,
   "Ubos": [
       {
           "Id": "160691407",
           "CreationDate": 1674491528,
           "LastName": "Boulanger",
           "FirstName": "Marie",
           "Birthday": 652117514,
           "Nationality": "FR",
           "Address": {
               "AddressLine1": "16 rue de Paris",
               "AddressLine2": null,
               "City": "Paris",
               "Region": "Île-de-France",
               "PostalCode": "75001",
               "Country": "FR"
           },
           "Birthplace": {
               "City": "Paris",
               "Country": "FR"
           },
           "IsActive": true
       }
   ]
}
```

### If further documents required

It may be that additional documentary evidence is required, such as the Shareholder Declaration form or another verification document. Any additional documents should be submitted in a KYC Document object.

[How to submit a KYC Document →](/guides/users/verification/documents/submission/how-to)

### If UBO added in error

It may be that the declaration contains information about someone who is not in fact a beneficial owner. If this happens, change the `IsActive` parameter of the UBO object to false to have them disregarded from the declaration. This action is irreversible, but another UBO can be added in their place.

> [**PUT** /v2.01/\{ClientId}/users/\{UserId}/kyc/ubodeclarations/\{UboDeclarationId}/ubos/\{UboId}](/api-reference/ubo-declarations/update-ubo)

```json REST theme={null}
{
   "Id": "160691407",
   "CreationDate": 1674491528,
   "LastName": "Boulanger",
   "FirstName": "Marie",
   "Birthday": 652117514,
   "Nationality": "FR",
   "Address": {
       "AddressLine1": "16 rue de Paris",
       "AddressLine2": null,
       "City": "Paris",
       "Region": "Île-de-France",
       "PostalCode": "75001",
       "Country": "FR"
   },
   "Birthplace": {
       "City": "Paris",
       "Country": "FR"
   },
   "IsActive": false
}
```

<hr />

## 8. Once remediated, re-submit the UBO Declaration

Once the reason that the declaration was marked `INCOMPLETE` has been addressed, re-submit the UBO Declaration by changing the Status to `VALIDATED_ASKED` (as in Step 4).

<Warning>
  **Caution - UBO Declaration must be consistent with documents**

  If additional documentary evidence was supplied to support the declaration, you must still ensure that the information in the UBO Declaration object is consistent with the documents before re-submitting.
</Warning>