# representativeRequiredFields

The `representativeRequiredFields` query returns the necessary fields for an owner or Ultimate Beneficial Owner (UBO) of an entity. This query response provides descriptions for all the fields used in the `createRepresentative` mutation, including how to handle multi-dimensional arrays for documents.

## Variables

| Field                | Type       | Description                                                    | Required                              |
|----------------------|------------|----------------------------------------------------------------|---------------------------------------|
| country              | ISO3166_1  | The country the representative resides.                        | true                                  |
| platform_id          | UUID       | UUID assigned to the platform to which the entity of the representative will belong. | false (required after June 15th 2026) |

## Documents Field

### documents

The `documents` field is a multi-dimensional array where each collection in the array represents a complete set of documents required for identity verification. I.E. **Inner brackets** mean “all of these are required together (AND).” **Outer brackets** mean “choose one of these sets (OR).”

Each document set is an array of document objects, and each document object contains the following fields:

| Field | Type   | Description                                                    |
|-------|--------|----------------------------------------------------------------|
| enum  | String | The type of document (e.g., passport).                       |
| type  | String | The purpose of the document (e.g., identity_verification).   |

### Example Structure

Below is an example structure for the `documents` field:

```json
"documents": [
  [
    {
      "enum": "passport",
      "type": "identity_verification"
    }
  ],
  [
    {
      "enum": "front_drivers_license",
      "type": "identity_verification"
    },
    {
      "enum": "back_drivers_license",
      "type": "identity_verification"
    }
  ],
  [
    {
      "enum": "front_permanent_residence_card",
      "type": "identity_verification"
    },
    {
      "enum": "back_permanent_residence_card",
      "type": "identity_verification"
    }
  ],
  [
    {
      "enum": "front_national_state_id",
      "type": "identity_verification"
    },
    {
      "enum": "back_national_state_id",
      "type": "identity_verification"
    }
  ]
]
```

Each inner array represents a complete set of documents that can be used for identity verification.

**The representative can provide any one of these sets.**

**One Representative will need to be designated as the signer for the entity.**

**The requirements are based on the residential country of the representative.**

To designate a representative assign the representative as `"is_signer": true`

Representatives with citizenship in a high-risk designated country will require special approval.

These requirements may be modified at any time as directed by compliance.

## Query

```graphql
query representativeRequiredFields (

$country: ISO3166_1
  $entity_id: UUID
) {

representativeRequiredFields (

country: $country
      entity_id: $entity_id
  ) {
	
documents {
        enum
        type
      }
      fields {
        variable
        regex
        example
        enum
      }
  }
}
```

### Example Response:

```json
{
  "data": {
    "representativeRequiredFields": {
      "fields": [
        {
          "variable": "first_name",
          "regex": "/^[a-zA-Z]{2,64}$/",
          "example": "John",
          "enum": null
        },
        {
          "variable": "last_name",
          "regex": "/^[a-zA-Z]{2,64}$/",
          "example": "Smith",
          "enum": null
        },
        {
          "variable": "citizenship",
          "regex": "/^[a-zA-Z]{2,64}$/",
          "example": "US citizen",
          "enum": null
        },
        {
          "variable": "residential_address",
          "regex": "/^.{2,64}$/",
          "example": "1 Street",
          "enum": null
        },
        {
          "variable": "residential_city",
          "regex": "/^.{2,64}$/",
          "example": "Austin",
          "enum": null
        },
        {
          "variable": "residential_state_province_region",
          "regex": "/^.{2,64}$/",
          "example": "TX",
          "enum": null
        },
        {
          "variable": "residential_country",
          "regex": "/^[A-Z]{2}$/",
          "example": "US",
          "enum": null
        },
        {
          "variable": "responsibility",
          "regex": null,
          "example": "director",
          "enum": [
            "ultimate_beneficial_owner",
            "authorized_representative",
            "director"
          ]
        },
        {
          "variable": "tax_number",
          "regex": null,
          "example": null,
          "enum": null
        },
        {
          "variable": "date_of_birth",
          "regex": "/d{4}-[01]d-[0-3]dT[0-2]d:[0-5]d:[0-5]d(?:.d+)?Z?",
          "example": "2018-01-04",
          "enum": null
        }
      ],

"documents": [
        [
          {
            "enum": "passport",
            "type": "identity_verification"
          }
        ]
      ]
    }
  }
}
```

Updated 2 months ago.