Individual recipients
An individual recipient is a person with a personal Xtrm account, identified by an account number that starts with PAT. Use these endpoints to check whether a person already has an account, create an individual recipient, update their profile details and list the individual recipients associated with your company.
Every request identifies your company in IssuerAccountNumber: the SPN account number tied to your API credentials or, with pseudo credentials, the SPN of the company you act on behalf of. When you create an individual recipient, Xtrm also creates a wallet in the currency of the recipient's country and reviews the account with identity and sanctions checks (KYC), so submit real, accurate information.
Business recipients (SPN accounts) have their own endpoints, such as CreateBeneficiary.
#Check whether an individual recipient exists
/API/v4/Beneficiary/CheckUserExistChecks whether an individual recipient's personal account (PAT) exists for an email address. If there is a match, Beneficiary returns minimal profile details for the account, including its account number (AccountNo), Status, and AccountIdentityLevel.
You don't need a connection to a person to find their account or to see its identity verification level.
To look up business recipients, use CheckBeneficiaryExist.
Body parameters
CheckUserExistobjectRequiredOperation wrapper.
Child parameters1
requestobjectRequiredThe request object.
Child parameters2
IssuerAccountNumberstringYour company's Xtrm account number, starting with
SPN: the account tied to the API credentials you use for this call. If you use pseudo credentials, this is theSPNof the company you act on behalf of.EmailstringThe email address to look up.
Response fields
CheckUserExistResponseobjectResponse wrapper.
Child parameters1
CheckUserExistResultobjectThe result of the lookup.
Child parameters2
Beneficiaryobject[]The individual recipients whose accounts match the email address.
Child parameters7
AccountNostringThe individual recipient's Xtrm account number, starting with
PAT.NamestringThe individual recipient's full name.
StatestringThe state, province, or region where the individual recipient lives, as saved on the account: for an account created with
CreateUser, theAddress.Regionyou sent, such asCA.CountrystringThe individual recipient's country, as its full name, e.g.
United States of America. It isn't the two-character code you send inCountryISO2.EmployerstringThe name of the individual recipient's employer.
StatusstringThe account's status:
Active,Email not verifiedorAccount pending approval. The lookup returns only accounts in one of these statuses.AccountIdentityLevelstringThe identity verification level of the personal account:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account;Advancedmeans the identity profile is complete.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: Create an individual recipient · List individual recipients · Search for existing company accounts
#Create an individual recipient
/API/v4/Register/CreateUserCreates a personal Xtrm account for an individual recipient, who can use it to make and receive all payments. Xtrm also creates a wallet for the recipient that holds the currency of the country you set in Address.CountryISO2. An account you create through the API is active straight away, and it's connected to your company, which also adds it to your individual recipients (GetPersonalBeneficiaries). If you call it with a client company's pseudo credentials, the new account is connected to the client company and to your platform. See Connections and manager services.
The response returns the new account number in UserID (starting with PAT) and the account's identity verification level in AccountIdentityLevel.
A batch payment pays existing accounts only, so create a person before you submit the batch that pays them. To check whether a person already has a personal account, use CheckUserExist first.
Important
Don't create test accounts or test email addresses on production servers.
Note
Submit real, accurate information. Xtrm reviews new accounts with identity and sanctions checks (KYC).
Body parameters
CreateUserobjectRequiredOperation wrapper.
Child parameters1
requestobjectRequiredThe request object.
Child parameters9
AddressobjectRequiredThe individual recipient's physical address.
Child parameters7
AddressLine1stringOptionalThe first line of the address, such as the street name and number.
AddressLine2stringOptionalThe second line of the address, if there is one.
AptSuitNumstringOptionalThe apartment, suite, or building number.
CitystringOptionalThe city of the address.
CountryISO2stringRequiredThe two-character ISO country code of the individual recipient's country of residence, e.g.
"US".PostalCodestringOptionalThe postal or ZIP code of the address.
RegionstringOptionalThe state, province, or region of the address, e.g.
"CA".
DateOfBirthobjectThe individual recipient's date of birth.
Child parameters3
DaystringOptionalThe day of the month (1 to 31), as a numeric string, e.g.
"15".MonthstringOptionalThe month (1 to 12), as a numeric string, e.g.
"08".YearstringOptionalThe four-digit year, as a string, e.g.
"1990".
EmailAddressstringRequiredThe individual recipient's primary contact email address.
EmailNotificationstringRequiredWhether the individual recipient gets an email saying the account was created. Boolean as a string:
"true"or"false".Allowed values:
true,false.IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account tied to the API credentials you use for this call. If you use pseudo credentials, this is theSPNof the company you act on behalf of.LegalFirstNamestringRequiredThe individual recipient's legal first name.
LegalLastNamestringRequiredThe individual recipient's legal last name.
MobilePhonestringOptionalThe individual recipient's primary mobile phone number. Don't include the country code: Xtrm determines it from the recipient's country.
TaxIdstringOptionalThe individual recipient's tax identification number, such as an SSN or national ID.
Response fields
CreateUserResponseobjectResponse wrapper.
Child parameters1
CreateUserResultobjectThe result of the request.
Child parameters3
UserIDstringThe Xtrm account number of the new individual recipient, starting with
PAT.AccountIdentityLevelstringThe identity verification level of the personal account:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account;Advancedmeans the identity profile is complete.OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: Check whether an individual recipient exists · Update an individual recipient · List individual recipients · List an individual recipient's wallets · Create an individual recipient's wallet · List countries
#Update an individual recipient
/API/v4/Register/UpdateUserUpdates the profile of an existing individual recipient, identified by UserId (starting with PAT): their legal name, address, date of birth, tax ID and mobile number. Your company needs a connection to the recipient, which it has with every account it creates with CreateUser. The call has no email field: to change a recipient's email address, use the Xtrm web app, where it's a manager service. See Connections and manager services.
Adding or changing the mobile number takes two calls, whether or not the profile already has one:
- Send the update with the new
MobileNumberandMobileCountryISO2, andOTPset to"". Xtrm texts a six-digit one-time password (OTP) to the new mobile number and responds with HTTP400,SuccesstrueandOne Time Password sent to user. Please resubmit with One Time Password.inErrors. Nothing in the profile changes yet, so treat this response as the cue to ask the recipient for the code, not as a failure. - Within 10 minutes, send the same request again, with every field and the same
MobileNumberandMobileCountryISO2, plus the code inOTP. Xtrm saves the new number, applies the rest of the update and returns HTTP200.
If the code is wrong or has expired, the second call returns HTTP 400 with Success false and Invalid one time password. A new one has been sent and the original has been expired. Please use the new one. Xtrm texts a new code to the new number: resubmit with that one. An update without MobileNumber needs no OTP and applies on the first call.
The response returns the account number in UserID and the account's identity verification level in AccountIdentityLevel.
Important
Your company must be connected to the individual recipient's personal account to update it.
Tip
To check the connection, call GetConnectedStatus. If you're not connected, call GetOTPAuthorizedVendor and then ValidateOTPAuthorizeVendor to connect.
Body parameters
UpdateUserobjectRequiredOperation wrapper.
Child parameters1
requestobjectRequiredThe request object.
Child parameters10
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account tied to the API credentials you use for this call. If you use pseudo credentials, this is theSPNof the company you act on behalf of.UserIdstringRequiredThe Xtrm account number of the individual recipient to update, starting with
PAT.LegalFirstNamestringRequiredThe individual recipient's legal first name.
LegalLastNamestringRequiredThe individual recipient's legal last name.
AddressobjectRequiredThe individual recipient's physical address.
Child parameters7
CountryISO2stringRequiredThe two-character ISO country code of the address, e.g.
"US".AddressLine1stringOptionalThe primary line of the address, such as the street name and number.
AddressLine2stringOptionalThe secondary line of the address, such as a building name, floor, or care-of details.
AptSuitNumstringOptionalThe apartment, suite, or unit number.
CitystringOptionalThe city of the address.
PostalCodestringOptionalThe postal or ZIP code of the address.
RegionstringOptionalThe state, province, or region of the address, e.g.
"CA".
DateOfBirthobjectThe individual recipient's date of birth.
Child parameters3
DaystringOptionalThe day of the month (1 to 31), as a numeric string, e.g.
"15".MonthstringOptionalThe month (1 to 12), as a numeric string, e.g.
"08".YearstringOptionalThe four-digit year, as a string, e.g.
"1990".
MobileCountryISO2stringOptionalThe two-character ISO country code for the new mobile phone number, e.g.
"US". Required when you sendMobileNumber.MobileNumberstringOptionalThe new mobile phone number for the individual recipient's profile, such as
"2135559876". Don't include the country code: Xtrm adds the calling code of the country inMobileCountryISO2. Adding or changing the number takes two calls and a one-time password: seeOTP. LeaveMobileNumberout when you aren't changing the number.OTPstringOptionalThe six-digit one-time password that Xtrm texts to the new mobile number, as a string. When you send
MobileNumber, sendOTPas""on the first call, then resubmit the same request with the code within 10 minutes. Not needed when you leave outMobileNumber.TaxIdstringOptionalThe individual recipient's tax identification number, such as an SSN or national ID.
Response fields
UpdateUserResponseobjectResponse wrapper.
Child parameters1
UpdateUserResultobjectThe result of the request.
Child parameters3
UserIDstringThe Xtrm account number of the updated individual recipient, starting with
PAT.nullon the first call that adds or changes the mobile number.AccountIdentityLevelstringThe identity verification level of the personal account:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account;Advancedmeans the identity profile is complete.nullon the first call that adds or changes the mobile number.OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false). It's alsotrueon the HTTP400response that tells you the one-time password was sent.Errorsstring[]Error messages when the call fails, or the
One Time Password sent to user. Please resubmit with One Time Password.message on the first call that adds or changes the mobile number. Once the update is applied, it'snullor an empty array[].
#Errors
| Message | Meaning |
|---|---|
400 · Invalid one-time password | The OTP is wrong, or more than 10 minutes have passed since Xtrm sent it. Success is false and Errors holds Invalid one time password. A new one has been sent and the original has been expired. Please use the new one. Xtrm texts a new code to the new mobile number, and nothing in the profile changes. Resubmit the same request with the new code. |
400 · Mobile country missing | You sent a new MobileNumber without a valid MobileCountryISO2. Errors holds MobileCountryISO2 is mandatory or MobileCountryISO2 is invalid. |
Related: Get the connection status of an account · Send a connection one-time password · Validate a connection one-time password · Create an individual recipient · List individual recipients
#List individual recipients
/API/v4/Beneficiary/GetPersonalBeneficiariesReturns a paginated list of the individual recipients associated with your company: every person your company created or connected to, and every person it paid in a batch once that payment completed. Each entry includes the recipient's account number (AccountNo), name, email address, location, employer, and AccountIdentityLevel.
Page through the list with Pagination: RecordsToSkip is the page number, starting at "1", and RecordsToTake is the page size, up to "100". For example, to get page 2 with a page size of 25, set RecordsToSkip to "2" and RecordsToTake to "25". The response's PaginationTotal returns the values used and the total number of records available in RecordsTotal.
To list business recipients, use GetBeneficiaries.
Body parameters
GetPersonalBeneficiariesobjectRequiredOperation wrapper.
Child parameters1
requestobjectRequiredThe request object.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account tied to the API credentials you use for this call. If you use pseudo credentials, this is theSPNof the company you act on behalf of.PaginationobjectRequiredPagination settings for the list.
Child parameters2
RecordsToSkipstringRequiredThe page number to return, starting at
"1". Integer as a string, e.g."2"for the second page."0"is rejected with HTTP400.RecordsToTakestringRequiredThe number of results per page, from
"1"to"100". Integer as a string, e.g."25". Keep the same value while you page through a list.
Response fields
GetPersonalBeneficiariesResponseobjectResponse wrapper.
Child parameters1
GetPersonalBeneficiaryResultobjectThe result of the request.
Child parameters3
Beneficiaryobject[]The individual recipients on this page of results.
Child parameters7
AccountNostringThe individual recipient's Xtrm account number, starting with
PAT.NamestringThe individual recipient's full name.
StatestringThe state, province, or region where the individual recipient lives, as saved on the account: for an account created with
CreateUser, theAddress.Regionyou sent, such asCA.CountrystringThe individual recipient's country, as its full name, e.g.
United States of America.EmployerstringThe name of the individual recipient's employer.
EmailstringThe individual recipient's primary contact email address.
AccountIdentityLevelstringThe identity verification level of the personal account:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account;Advancedmeans the identity profile is complete.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
PaginationTotalobjectPagination details for this page of results.
Child parameters3
RecordsToSkipintegerThe page number of these results, as sent in the request.
RecordsToTakeintegerThe maximum number of results requested per page.
RecordsTotalintegerThe total number of records available for this query.
Related: Check whether an individual recipient exists · Create an individual recipient · Update an individual recipient · List an individual recipient's wallets · List business recipients