Customers

A customer is a person or an organization you have a direct relationship with. In a transfer, your customer is the originator of a withdrawal or the beneficiary of a deposit. Register each customer once with their identifying details, and your transfers then refer to them by your own id instead of carrying their data every time.

Register a customer

Send the customer’s details as an IVMS-101 person, under an id of your own, with POST /api/v1/customers. Include what your jurisdiction’s Travel Rule asks for: the name and an account number for the account you hold for them. Depending on the jurisdiction, add more identifiers, such as the date and place of birth, the address or a national identity number. Data collection lists the fields and where each one comes from.

Request

cURLNode.jsPythonAPI reference

curl https://sandbox.notabene.id/api/v1/customers \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
    "type": "Individual",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "Silva",
                "secondaryIdentifier": "Ana",
                "naturalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "HOME",
              "streetName": "Rua Augusta",
              "buildingNumber": "100",
              "postCode": "1100-053",
              "townName": "Lisboa",
              "country": "PT"
            }
          ],
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1988-03-02",
            "placeOfBirth": "Porto"
          }
        },
        "accountNumber": [
          "acc-ana-001"
        ]
      }
    }
  }'const response = await fetch('https://sandbox.notabene.id/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
    "type": "Individual",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "Silva",
                "secondaryIdentifier": "Ana",
                "naturalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "HOME",
              "streetName": "Rua Augusta",
              "buildingNumber": "100",
              "postCode": "1100-053",
              "townName": "Lisboa",
              "country": "PT"
            }
          ],
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1988-03-02",
            "placeOfBirth": "Porto"
          }
        },
        "accountNumber": [
          "acc-ana-001"
        ]
      }
    }
  }),
});
const answer = response.status === 204 ? null : await response.json();import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/customers',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
      "type": "Individual",
      "jurisdiction": "PT",
      "profile": {
        "ivms": {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Silva",
                  "secondaryIdentifier": "Ana",
                  "naturalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "Rua Augusta",
                "buildingNumber": "100",
                "postCode": "1100-053",
                "townName": "Lisboa",
                "country": "PT"
              }
            ],
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1988-03-02",
              "placeOfBirth": "Porto"
            }
          },
          "accountNumber": [
            "acc-ana-001"
          ]
        }
      }
    },
)
answer = None if response.status_code == 204 else response.json()

What to replace

urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27: An id of your own for the customer
Silva: Your customer’s last name
Ana: Your customer’s first names
Rua Augusta: Your customer’s street
100: Your customer’s building number
1100-053: Your customer’s postcode
Lisboa: Your customer’s town
1988-03-02: Your customer’s date of birth, as YYYY-MM-DD
Porto: Your customer’s place of birth
acc-ana-001: The account you hold for your customer

Response201

{
  "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
  "type": "Individual",
  "relationship": "OurCustomer",
  "status": "New",
  "jurisdiction": "PT",
  "created_at": "2026-10-16T09:12:04Z",
  "updated_at": "2026-10-16T09:12:04Z"
}

curl https://sandbox.notabene.id/api/v1/customers \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
    "type": "Individual",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "Silva",
                "secondaryIdentifier": "Ana",
                "naturalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "HOME",
              "streetName": "Rua Augusta",
              "buildingNumber": "100",
              "postCode": "1100-053",
              "townName": "Lisboa",
              "country": "PT"
            }
          ],
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1988-03-02",
            "placeOfBirth": "Porto"
          }
        },
        "accountNumber": [
          "acc-ana-001"
        ]
      }
    }
  }'

const response = await fetch('https://sandbox.notabene.id/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
    "type": "Individual",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "Silva",
                "secondaryIdentifier": "Ana",
                "naturalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "HOME",
              "streetName": "Rua Augusta",
              "buildingNumber": "100",
              "postCode": "1100-053",
              "townName": "Lisboa",
              "country": "PT"
            }
          ],
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1988-03-02",
            "placeOfBirth": "Porto"
          }
        },
        "accountNumber": [
          "acc-ana-001"
        ]
      }
    }
  }),
});
const answer = response.status === 204 ? null : await response.json();

import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/customers',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
      "type": "Individual",
      "jurisdiction": "PT",
      "profile": {
        "ivms": {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Silva",
                  "secondaryIdentifier": "Ana",
                  "naturalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "Rua Augusta",
                "buildingNumber": "100",
                "postCode": "1100-053",
                "townName": "Lisboa",
                "country": "PT"
              }
            ],
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1988-03-02",
              "placeOfBirth": "Porto"
            }
          },
          "accountNumber": [
            "acc-ana-001"
          ]
        }
      }
    },
)
answer = None if response.status_code == 204 else response.json()

{
  "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27",
  "type": "Individual",
  "relationship": "OurCustomer",
  "status": "New",
  "jurisdiction": "PT",
  "created_at": "2026-10-16T09:12:04Z",
  "updated_at": "2026-10-16T09:12:04Z"
}

The customer record that comes back does not repeat the profile. Registering the same id again answers 409 with customer already exists, so a retry never creates a second record.

Field	What to send
`id` Required string, IRI	Your own unique IRI for the customer, for example a `urn:uuid`. Your transfers name the customer with it, as `originator_id` or `beneficiary_id`.
`type` Optional string	`Individual` or `Organization`.
`jurisdiction` Optional string, ISO 3166-1 alpha-2	The customer’s country, as an ISO 3166-1 alpha-2 code.
`profile.ivms` object, IVMS-101	The customer as an IVMS-101 person, with exactly one of `naturalPerson` or `legalPerson`, and `accountNumber` for the account you hold for them.
`profile.ivms_encrypted` string, JWE	Instead of `ivms`, the profile encrypted by you as a JWE compact string. Notabene passes it on without decrypting it. List the IVMS-101 fields it contains in `ivms_encrypted_fields`.

Field	What to send
`id` (required), string, IRI	Your own unique IRI for the customer, for example a `urn:uuid`. Your transfers name the customer with it, as `originator_id` or `beneficiary_id`.
`type` (optional), string	`Individual` or `Organization`.
`jurisdiction` (optional), string, ISO 3166-1 alpha-2	The customer’s country, as an ISO 3166-1 alpha-2 code.
`profile.ivms`, object, IVMS-101	The customer as an IVMS-101 person, with exactly one of `naturalPerson` or `legalPerson`, and `accountNumber` for the account you hold for them.
`profile.ivms_encrypted`, string, JWE	Instead of `ivms`, the profile encrypted by you as a JWE compact string. Notabene passes it on without decrypting it. List the IVMS-101 fields it contains in `ivms_encrypted_fields`.

An organization

For a company, send a legalPerson instead, with type set to Organization.

Request

cURLNode.jsPythonAPI reference

curl https://sandbox.notabene.id/api/v1/customers \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
    "type": "Organization",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lusa Digital, Lda",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "nationalIdentifier": "5493001KJTIIGC8Y1R12",
            "nationalIdentifierType": "LEIX"
          },
          "countryOfRegistration": "PT"
        },
        "accountNumber": [
          "acc-lusa-001"
        ]
      }
    }
  }'const response = await fetch('https://sandbox.notabene.id/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
    "type": "Organization",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lusa Digital, Lda",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "nationalIdentifier": "5493001KJTIIGC8Y1R12",
            "nationalIdentifierType": "LEIX"
          },
          "countryOfRegistration": "PT"
        },
        "accountNumber": [
          "acc-lusa-001"
        ]
      }
    }
  }),
});
const answer = response.status === 204 ? null : await response.json();import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/customers',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
      "type": "Organization",
      "jurisdiction": "PT",
      "profile": {
        "ivms": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Lusa Digital, Lda",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "nationalIdentification": {
              "nationalIdentifier": "5493001KJTIIGC8Y1R12",
              "nationalIdentifierType": "LEIX"
            },
            "countryOfRegistration": "PT"
          },
          "accountNumber": [
            "acc-lusa-001"
          ]
        }
      }
    },
)
answer = None if response.status_code == 204 else response.json()

What to replace

urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21: An id of your own for the customer
Lusa Digital, Lda: The organization’s legal name
5493001KJTIIGC8Y1R12: The organization’s LEI
acc-lusa-001: The account you hold for the organization

Response201

{
  "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
  "type": "Organization",
  "relationship": "OurCustomer",
  "status": "New",
  "jurisdiction": "PT",
  "created_at": "2026-10-20T09:15:02Z",
  "updated_at": "2026-10-20T09:15:02Z"
}

curl https://sandbox.notabene.id/api/v1/customers \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
    "type": "Organization",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lusa Digital, Lda",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "nationalIdentifier": "5493001KJTIIGC8Y1R12",
            "nationalIdentifierType": "LEIX"
          },
          "countryOfRegistration": "PT"
        },
        "accountNumber": [
          "acc-lusa-001"
        ]
      }
    }
  }'

const response = await fetch('https://sandbox.notabene.id/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
    "type": "Organization",
    "jurisdiction": "PT",
    "profile": {
      "ivms": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lusa Digital, Lda",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "nationalIdentifier": "5493001KJTIIGC8Y1R12",
            "nationalIdentifierType": "LEIX"
          },
          "countryOfRegistration": "PT"
        },
        "accountNumber": [
          "acc-lusa-001"
        ]
      }
    }
  }),
});
const answer = response.status === 204 ? null : await response.json();

import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/customers',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
      "type": "Organization",
      "jurisdiction": "PT",
      "profile": {
        "ivms": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Lusa Digital, Lda",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "nationalIdentification": {
              "nationalIdentifier": "5493001KJTIIGC8Y1R12",
              "nationalIdentifierType": "LEIX"
            },
            "countryOfRegistration": "PT"
          },
          "accountNumber": [
            "acc-lusa-001"
          ]
        }
      }
    },
)
answer = None if response.status_code == 204 else response.json()

{
  "id": "urn:uuid:7d1e9b40-2a6c-4f3e-9d8b-1c5a0e6f4b21",
  "type": "Organization",
  "relationship": "OurCustomer",
  "status": "New",
  "jurisdiction": "PT",
  "created_at": "2026-10-20T09:15:02Z",
  "updated_at": "2026-10-20T09:15:02Z"
}

Look up, list, update and remove

Call	What it does
GET`/api/v1/customers/{id}`	Returns one customer. It answers 404 with `customer not found` when the id is not registered.
GET`/api/v1/customers`	Lists your customers, newest first, one page at a time. Pass `limit`, and `cursor` with the `next_cursor` of the previous page.
PUT`/api/v1/customers/{id}`	Updates the jurisdiction or the profile. Fields you leave out stay as they are.
DELETE`/api/v1/customers/{id}`	Removes the customer. It answers 409 once a wallet or a transfer refers to the customer.

Call	What it does
`GET /api/v1/customers/{id}`	Returns one customer. It answers `404` with `customer not found` when the id is not registered.
`GET /api/v1/customers`	Lists your customers, newest first, one page at a time. Pass `limit`, and `cursor` with the `next_cursor` of the previous page.
`PUT /api/v1/customers/{id}`	Updates the jurisdiction or the profile. Fields you leave out stay as they are.
`DELETE /api/v1/customers/{id}`	Removes the customer. It answers `409` once a wallet or a transfer refers to the customer.

Once your Travel Rule data has been sent for a transfer, the customer’s details can no longer be edited on that transfer, so update the customer instead.

Your customers and the counterparties’ customers

Notabene keeps three kinds of customer records, told apart by relationship. To list one kind, pass its relationship as type to GET /api/v1/customers, as in ?type=CounterpartyCustomer, and without type you get your own customers.

Relationship	How the record is created
`OurCustomer`	You register the customer with POST`/api/v1/customers`.
`CounterpartyCustomer`	Notabene records it when one of your transfers names a customer of another institution, for example the beneficiary of a withdrawal.
`OurCustomerReceived`	A counterparty institution named them as your customer on a transfer it sent you. It is their claim, kept apart from your own record.

Relationship	How the record is created
`OurCustomer`	You register the customer with `POST /api/v1/customers`.
`CounterpartyCustomer`	Notabene records it when one of your transfers names a customer of another institution, for example the beneficiary of a withdrawal.
`OurCustomerReceived`	A counterparty institution named them as your customer on a transfer it sent you. It is their claim, kept apart from your own record.

In the dashboard, your own customers are under My Organization › My Customers, and the counterparties’ customers under Network › Customers. Updating a counterparty’s customer with PUT records your own view of that customer, and what the counterparty sent is kept as theirs.

Wallets

Register the addresses you hold for your customers and record proofs for their self-hosted wallets with the calls in Wallets. Counterparty institutions can then find you from an address, and Notabene confirms your deposit addresses by itself, as described in Deposits.

Customers and your policies

Notabene does not screen your own customers against sanctions lists. A customer without a policy of its own is Not reviewed, and gets the verdict you set for Not reviewed customers, if you set one. The counterparties’ customers can be screened at each transfer when you connect a sanctions-screening provider, and your policies decide what to do with the result.