Skip to content
/
Identity create

Identity create

Request

Low level identity onboarding

Security
HMACAuth
Bodyapplication/jsonrequired
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
givenNamestring

Company representative first name.

Example:"Joe"
surnamestring

Company representative last name.

Example:"Bloggs"
dateOfBirthstring, (date)

Date of birth in YYYY-MM-DD format. Must be a past date.

Example:"1990-05-21"
emailstring, (email)

Email address of the customer.

Example:"[email protected]"
taxIdTypestring(TaxIdType)

The category of tax or government identifier supplied in taxId. The correct value depends on the customer's country and the identifier type accepted for that country.

ValueDescription
identity_cardA government-issued identity card number used for identity or tax reporting in the customer's country.
tax_idA tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent.
national_numberA national, citizen, resident, or social insurance number used to identify an individual in their country.
ssnA Social Security Number, generally used for US individuals.
Enum:"identity_card""tax_id""national_number""ssn"
Example:"tax_id"
taxIdstring(TaxId)

Tax identification number.

See TIN validation.

Example:"123-11-123"
taxStatestring

Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.

Example:"IL"
residentialAddressobject(Residential Address)

Customer's residential address. Required for identity verification and compliance purposes.

Important: This must be the customer's current residential address, not a PO Box or business address.

curl -i -X POST \
  https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities/basic \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityReference": "customer-12345",
    "givenName": "John",
    "surname": "Doe",
    "dateOfBirth": "1990-01-15",
    "email": "[email protected]",
    "residentialAddress": {
      "addressLine": "123 Main Street",
      "suburb": "Sydney",
      "state": "NSW",
      "postCode": "2000",
      "country": "AU"
    }
  }'

Responses

The identity has been created

Bodyapplication/json
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
createdAtstring, (date-time)required

The UTC date time of the identity.

Example:"2023-06-05T19:53:08.320Z"
Response
{
  "identityReference": "customer-12345",
  "createdAt": "2024-01-15T10:30:00Z"
}
© Banxa 2026