---
title: "Set submission relations"
method: POST
path: "/v1/kyc/submissions/{submissionId}/relations"
---

# Set submission relations

`POST /v1/kyc/submissions/{submissionId}/relations`

## Request

- Base URL: `https://api.sandbox.due.network`
- URL: `https://api.sandbox.due.network/v1/kyc/submissions/{submissionId}/relations`
- Auth: HTTP bearer

Sets beneficiary relations for a KYC submission.

## Path parameters

- `submissionId` string, required

## Request body

- KycEntitiesBeneficiary[]
  - `applicantId` string
  - `roles` string[]
  - `shareSize` string

## Response `200`

OK

- KycEntitiesSubmission
  - `id` string
  - `ownerId` string
  - `applicantId` string
  - `status` string
  - `info` KycInfoApplicantInfo
    - `firstName` string
    - `lastName` string
    - `dob` TypesOptionalTypesDate
      - `Val` TypesDate
      - `NotNull` boolean
    - `companyName` string
    - `registrationNumber` string
    - `registrationDate` TypesOptionalTypesDate
      - `Val` TypesDate
      - `NotNull` boolean
    - `taxId` string
    - `accountType` string
    - `address` KycRequiredInfoAddress
      - `country` string
      - `postCode` string
      - `town` string
      - `street` string
      - `subStreet` string
      - `state` string
      - `stateCode` string
      - `buildingName` string
      - `flatNumber` string
      - `buildingNumber` string
    - `bvn` string
    - `entityType` string
    - `nationality` string
    - `phone` string
    - `email` string
    - `postalAddress` string
    - `ssn` string
    - `tin` string
    - `cpf` string
    - `website` string
    - `location` KycRequiredInfoLocation
      - `latitude` string
      - `longitude` string
    - `residenceCountry` string
    - `companyDescription` string
    - `birthCountry` string
  - `requirements` union[]
    - union
      - KycEntitiesRequirementsSchemaStatic
        - `info` DueReflectFieldDescriptor[]
          - `key` string
          - `type` string
          - `oneOf` string[]
          - `required` boolean
          - `requiredIf` string
          - `excludedUnless` string
          - `fields` DueReflectFieldDescriptor[]
        - `documents` KycDocumentKYCDocumentRequirementSet[]
          - `category` string
          - `oneOf` KycDocumentKYCDocumentRequirement[]
            - `type` string
            - `variants` string[]
            - `issuingCountries` string[]
          - `maxAgeDays` integer
        - `questionnaires` KycQuestionnaireQuestionnaireTemplate[]
          - `templateId` string
          - `questions` KycQuestionnaireQuestion[]
            - `id` string
            - `title` string
            - `description` string
            - `requiredWhen` KycQuestionnaireRequiredCondition
              - …
            - `schema` union
              - …
        - `agreements` KycEntitiesAgreementRequirement[]
          - `documentSetId` string
          - `consentText` string
        - `externalChecks` KycEntitiesExternalCheckRequirement[]
          - `type` string
        - `beneficiaries` KycEntitiesBeneficiariesRequirement
          - `minTotalShare` string
          - `minBeneficiariesByRole` object
        - `kind` string, required
      - KycEntitiesRequirementsSchemaConditional
        - `if` union
          - KycEntitiesRequirementsSchemaStatic
            - `info` DueReflectFieldDescriptor[]
              - …
            - `documents` KycDocumentKYCDocumentRequirementSet[]
              - …
            - `questionnaires` KycQuestionnaireQuestionnaireTemplate[]
              - …
            - `agreements` KycEntitiesAgreementRequirement[]
              - …
            - `externalChecks` KycEntitiesExternalCheckRequirement[]
              - …
            - `beneficiaries` KycEntitiesBeneficiariesRequirement
              - …
            - `kind` string, required
          - KycEntitiesRequirementsSchemaConditional (recursive)
          - KycEntitiesRequirementsSchemaOneOf
            - `oneOf` union[]
              - …
            - `kind` string, required
        - `then` union
          - KycEntitiesRequirementsSchemaStatic
            - `info` DueReflectFieldDescriptor[]
              - …
            - `documents` KycDocumentKYCDocumentRequirementSet[]
              - …
            - `questionnaires` KycQuestionnaireQuestionnaireTemplate[]
              - …
            - `agreements` KycEntitiesAgreementRequirement[]
              - …
            - `externalChecks` KycEntitiesExternalCheckRequirement[]
              - …
            - `beneficiaries` KycEntitiesBeneficiariesRequirement
              - …
            - `kind` string, required
          - KycEntitiesRequirementsSchemaConditional (recursive)
          - KycEntitiesRequirementsSchemaOneOf
            - `oneOf` union[]
              - …
            - `kind` string, required
        - `kind` string, required
      - KycEntitiesRequirementsSchemaOneOf
        - `oneOf` union[]
          - union
            - KycEntitiesRequirementsSchemaStatic
              - …
            - KycEntitiesRequirementsSchemaConditional
              - …
            - KycEntitiesRequirementsSchemaOneOf (recursive)
        - `kind` string, required
  - `agreements` KycEntitiesAgreement[]
    - `documentSet` TransfersModelsV2DocumentSet
      - `id` string
      - `links` object
    - `acceptedAt` string
  - `externalChecks` KycEntitiesExternalCheck[]
    - `id` string
    - `type` string
    - `status` string
    - `externalId` string
  - `documents` KycDocumentKYCDocument[]
    - `filename` string
    - `type` string
    - `variant` string
    - `issuingCountry` string
    - `uploadedAt` string, date-time
    - `expiresAt` TypesOptionalTypesDate
      - `Val` TypesDate
      - `NotNull` boolean
  - `questionnaires` KycQuestionnaireQuestionnaireAnswered[]
    - `id` string
    - `templateId` string
    - `answers` KycQuestionnaireAnswer[]
      - `id` string
      - `value` string[]
  - `beneficiaries` KycEntitiesBeneficiary[]
    - `applicantId` string
    - `roles` string[]
    - `shareSize` string
  - `presetCode` string
  - `source` string
  - `subject` KycEntitiesSubject
    - `Value` object

## Changes

- **2026-11-03** `5799e4dcc4a8`: 29 breaking, 31 info
  - the response property `info/address` became optional for the status `200`
  - the response property `info/address/postCode` became optional for the status `200`
  - the response property `info/address/street` became optional for the status `200`
  - the response property `info/address/town` became optional for the status `200`
  - …56 more

[Operation history](https://skmtc.dev/due/apis/accounts-api/changes/v1/kyc/submissions/:submissionId/relations/post.md)

---

[API](https://skmtc.dev/due/apis/accounts-api.md) - [All operations](https://skmtc.dev/due/apis/accounts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/due/apis/accounts-api/revisions/5799e4dcc4a8?raw)