Entities

Replace beneficial owners

Replaces the business’s entire set of beneficial owners. Entries carrying an id are updated, entries without one are created, and any person the payload omits is deleted.

Replace rather than patch because ownership percentages are only meaningful as a set: the currency provider validates their total, so a partial update has no coherent meaning. Read the current set first, modify it, and send it back whole.

Recording an fx-account-holder is what unblocks international-fx accounts. Check GET /limitations afterwards to confirm nothing else is outstanding.

PUT

entities

{entityId}

beneficial-owners

Replace beneficial owners

const options = {
  method: 'PUT',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        firstName: 'Dana',
        lastName: 'Okonjo',
        dateOfBirth: '1984-03-11',
        address: {
          line1: '500 Congress Ave',
          city: 'Austin',
          state: 'TX',
          postalCode: '78701',
          countryCode: 'US'
        },
        usResident: true,
        ownershipPercentage: 0.6,
        jobTitle: 'chief-executive-officer',
        taxInfo: {type: 'ssn', identifier: '123-45-6789'},
        types: ['ubo', 'director', 'fx-account-holder'],
        email: '[email protected]'
      }
    ]
  })
};

fetch('https://api.melio.com/v2/entities/{entityId}/beneficial-owners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/entities/{entityId}/beneficial-owners"

payload = { "data": [
        {
            "firstName": "Dana",
            "lastName": "Okonjo",
            "dateOfBirth": "1984-03-11",
            "address": {
                "line1": "500 Congress Ave",
                "city": "Austin",
                "state": "TX",
                "postalCode": "78701",
                "countryCode": "US"
            },
            "usResident": True,
            "ownershipPercentage": 0.6,
            "jobTitle": "chief-executive-officer",
            "taxInfo": {
                "type": "ssn",
                "identifier": "123-45-6789"
            },
            "types": ["ubo", "director", "fx-account-holder"],
            "email": "[email protected]"
        }
    ] }
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

curl --request PUT \
  --url https://api.melio.com/v2/entities/{entityId}/beneficial-owners \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "data": [
    {
      "firstName": "Dana",
      "lastName": "Okonjo",
      "dateOfBirth": "1984-03-11",
      "address": {
        "line1": "500 Congress Ave",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "countryCode": "US"
      },
      "usResident": true,
      "ownershipPercentage": 0.6,
      "jobTitle": "chief-executive-officer",
      "taxInfo": {
        "type": "ssn",
        "identifier": "123-45-6789"
      },
      "types": [
        "ubo",
        "director",
        "fx-account-holder"
      ],
      "email": "[email protected]"
    }
  ]
}
'

HttpResponse<String> response = Unirest.put("https://api.melio.com/v2/entities/{entityId}/beneficial-owners")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/entities/{entityId}/beneficial-owners")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/entities/{entityId}/beneficial-owners"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": [
    {
      "id": 123,
      "firstName": "<string>",
      "lastName": "<string>",
      "dateOfBirth": "2023-12-25",
      "address": {
        "line1": "<string>",
        "city": "<string>",
        "postalCode": "<string>",
        "countryCode": "<string>",
        "line2": "<string>",
        "state": "<string>"
      },
      "usResident": true,
      "hasIdentityDocument": true,
      "types": [
        "ubo"
      ],
      "ownershipPercentage": 123,
      "jobTitle": "chief-executive-officer",
      "taxInfo": {
        "type": "ssn",
        "identifierLast4": "<string>"
      },
      "internationalIdType": "passport",
      "internationalId": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

api-key

string

header

required

Path Parameters

entityId

string

required

Body

application/json

data

object[]

required

Hide child attributes

data.firstName

string

required

Minimum string length: 2

data.lastName

string

required

Minimum string length: 2

data.dateOfBirth

string<date>

required

data.address

object

required

The person's home address. Unlike a counterparty address this may be in the US — send countryCode: US for a US resident.

Hide child attributes

data.address.line1

string

required

Street address. Must be a real street address, not a PO box.

data.address.city

string

required

data.address.postalCode

string

required

data.address.countryCode

string

required

Two-letter ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Za-z]{2}$

data.address.line2

string

data.address.state

string

State, province or region. Optional — send an empty string where the country has none.

data.usResident

boolean

required

data.types

enum<string>[]

required

Minimum array length: 1

The role a person holds in the business. ubo is an ultimate beneficial owner (someone with a material ownership stake), director is a control person, and fx-account-holder is the individual who acts for the business towards the currency provider. One person may hold several roles; exactly one person must be the fx-account-holder.

Available options:

ubo,

director,

fx-account-holder

data.id

integer

The id of an existing person to update. Omit to create.

data.ownershipPercentage

number

Share of the business held, as a decimal (0.25 = 25%). Required for anyone whose types include ubo. The currency provider validates the total across all ubo entries, so send the complete set in one request.

Required range: 0 <= x <= 1

data.jobTitle

enum<string>

Available options:

chief-executive-officer,

chief-financial-officer,

managing-member,

general-partner,

president,

vice-president,

treasurer

data.taxInfo

object

Required when usResident is true.

Hide child attributes

data.taxInfo.type

enum<string>

required

Available options:

ssn,

itin

data.taxInfo.identifier

string

required

9-digit identifier, optionally dash-separated.

Pattern: ^[0-9]{3}-?[0-9]{2}-?[0-9]{4}$

data.internationalIdType

enum<string>

Required when usResident is false.

Available options:

passport,

driver-license,

national-id

data.internationalId

string

Required when usResident is false.

data.email

string<email>

data.phoneNumber

string

data.identityDocument

object

A scan or photo of this person's government-issued ID, uploaded with POST /attachments.

Optional in general. The FX provider insists on it in exactly two cases, and the request is rejected with 400 VALIDATION_ERROR naming the person if it is absent: when usResident is false, or for every beneficial owner when the entity's businessType is sole-proprietorship — including US residents.

Only the front is required. The provider's guidance asks for both sides of a driver's licence or national ID, but nothing downstream reads the back, so a front-only upload is accepted here exactly as it is elsewhere in Melio. Send backAttachmentId when you have it.

Write-only: BeneficialOwner reports hasIdentityDocument and never a reference to the file.

Hide child attributes

data.identityDocument.frontAttachmentId

string

required

Attachment id (att_) of the front of the ID.

Example:

"att_9f8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

data.identityDocument.backAttachmentId

string

Attachment id of the back, where the ID has one. Must differ from the front.

Response

The business's beneficial owners after the replacement.

data

object[]

required

Hide child attributes

data.id

integer

required

data.firstName

string

required

data.lastName

string

required

data.dateOfBirth

string<date>

required

data.address

object

required

A counterparty address outside the US. Unlike Address, state is free-form (most countries have no state; send an empty string or omit it) and postalCode is not a US ZIP. countryCode is required and must not be US — a US-domiciled counterparty belongs on a domestic account type.

Hide child attributes

data.address.line1

string

required

Street address. Must be a real street address, not a PO box.

data.address.city

string

required

data.address.postalCode

string

required

data.address.countryCode

string

required

Two-letter ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Za-z]{2}$

data.address.line2

string

data.address.state

string

State, province or region. Optional — send an empty string where the country has none.

data.usResident

boolean

required

data.hasIdentityDocument

boolean

required

Whether a government ID is on file for this person. The document itself cannot be read back through this API.

data.types

enum<string>[]

required

Available options:

ubo,

director,

fx-account-holder

data.ownershipPercentage

number

Decimal share (0.25 = 25%)

data.jobTitle

enum<string>

Available options:

chief-executive-officer,

chief-financial-officer,

managing-member,

general-partner,

president,

vice-president,

treasurer

data.taxInfo

object

Hide child attributes

data.taxInfo.type

enum<string>

Available options:

ssn,

itin

data.taxInfo.identifierLast4

string

data.internationalIdType

enum<string>

Available options:

passport,

driver-license,

national-id

data.internationalId

string

Last four characters of the identifier on file

data.email

string

data.phoneNumber

string

data.createdAt

string<date-time>

data.updatedAt

string<date-time>

Replace beneficial owners

const options = {
  method: 'PUT',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        firstName: 'Dana',
        lastName: 'Okonjo',
        dateOfBirth: '1984-03-11',
        address: {
          line1: '500 Congress Ave',
          city: 'Austin',
          state: 'TX',
          postalCode: '78701',
          countryCode: 'US'
        },
        usResident: true,
        ownershipPercentage: 0.6,
        jobTitle: 'chief-executive-officer',
        taxInfo: {type: 'ssn', identifier: '123-45-6789'},
        types: ['ubo', 'director', 'fx-account-holder'],
        email: '[email protected]'
      }
    ]
  })
};

fetch('https://api.melio.com/v2/entities/{entityId}/beneficial-owners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/entities/{entityId}/beneficial-owners"

payload = { "data": [
        {
            "firstName": "Dana",
            "lastName": "Okonjo",
            "dateOfBirth": "1984-03-11",
            "address": {
                "line1": "500 Congress Ave",
                "city": "Austin",
                "state": "TX",
                "postalCode": "78701",
                "countryCode": "US"
            },
            "usResident": True,
            "ownershipPercentage": 0.6,
            "jobTitle": "chief-executive-officer",
            "taxInfo": {
                "type": "ssn",
                "identifier": "123-45-6789"
            },
            "types": ["ubo", "director", "fx-account-holder"],
            "email": "[email protected]"
        }
    ] }
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

curl --request PUT \
  --url https://api.melio.com/v2/entities/{entityId}/beneficial-owners \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "data": [
    {
      "firstName": "Dana",
      "lastName": "Okonjo",
      "dateOfBirth": "1984-03-11",
      "address": {
        "line1": "500 Congress Ave",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "countryCode": "US"
      },
      "usResident": true,
      "ownershipPercentage": 0.6,
      "jobTitle": "chief-executive-officer",
      "taxInfo": {
        "type": "ssn",
        "identifier": "123-45-6789"
      },
      "types": [
        "ubo",
        "director",
        "fx-account-holder"
      ],
      "email": "[email protected]"
    }
  ]
}
'

HttpResponse<String> response = Unirest.put("https://api.melio.com/v2/entities/{entityId}/beneficial-owners")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/entities/{entityId}/beneficial-owners")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/entities/{entityId}/beneficial-owners"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"firstName\": \"Dana\",\n      \"lastName\": \"Okonjo\",\n      \"dateOfBirth\": \"1984-03-11\",\n      \"address\": {\n        \"line1\": \"500 Congress Ave\",\n        \"city\": \"Austin\",\n        \"state\": \"TX\",\n        \"postalCode\": \"78701\",\n        \"countryCode\": \"US\"\n      },\n      \"usResident\": true,\n      \"ownershipPercentage\": 0.6,\n      \"jobTitle\": \"chief-executive-officer\",\n      \"taxInfo\": {\n        \"type\": \"ssn\",\n        \"identifier\": \"123-45-6789\"\n      },\n      \"types\": [\n        \"ubo\",\n        \"director\",\n        \"fx-account-holder\"\n      ],\n      \"email\": \"[email protected]\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "data": [
    {
      "id": 123,
      "firstName": "<string>",
      "lastName": "<string>",
      "dateOfBirth": "2023-12-25",
      "address": {
        "line1": "<string>",
        "city": "<string>",
        "postalCode": "<string>",
        "countryCode": "<string>",
        "line2": "<string>",
        "state": "<string>"
      },
      "usResident": true,
      "hasIdentityDocument": true,
      "types": [
        "ubo"
      ],
      "ownershipPercentage": 123,
      "jobTitle": "chief-executive-officer",
      "taxInfo": {
        "type": "ssn",
        "identifierLast4": "<string>"
      },
      "internationalIdType": "passport",
      "internationalId": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "<string>",
    "details": {}
  }
}

Entities

Accounts

Attachments

Payments

Tools

Webhooks

Replace beneficial owners

Authorizations

Path Parameters

Body

Response