API reference

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

POST/API/v4/Beneficiary/CheckUserExist

Checks 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

  • CheckUserExistobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters2
      • IssuerAccountNumberstring

        Your 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 the SPN of the company you act on behalf of.

      • Emailstring

        The email address to look up.

Response fields

  • CheckUserExistResponseobject

    Response wrapper.

    Child parameters1
    • CheckUserExistResultobject

      The result of the lookup.

      Child parameters2
      • Beneficiaryobject[]

        The individual recipients whose accounts match the email address.

        Child parameters7
        • AccountNostring

          The individual recipient's Xtrm account number, starting with PAT.

        • Namestring

          The individual recipient's full name.

        • Statestring

          The state, province, or region where the individual recipient lives, as saved on the account: for an account created with CreateUser, the Address.Region you sent, such as CA.

        • Countrystring

          The individual recipient's country, as its full name, e.g. United States of America. It isn't the two-character code you send in CountryISO2.

        • Employerstring

          The name of the individual recipient's employer.

        • Statusstring

          The account's status: Active, Email not verified or Account pending approval. The lookup returns only accounts in one of these statuses.

        • AccountIdentityLevelstring

          The identity verification level of the personal account: Draft, Basic, Standard or Advanced, from the lowest level to the highest. Draft means only the bare minimum details are on the account; Advanced means the identity profile is complete.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create an individual recipient · List individual recipients · Search for existing company accounts

#Create an individual recipient

POST/API/v4/Register/CreateUser

Creates 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.

Note

Submit real, accurate information. Xtrm reviews new accounts with identity and sanctions checks (KYC).

Body parameters

  • CreateUserobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters9
      • AddressobjectRequired

        The individual recipient's physical address.

        Child parameters7
        • AddressLine1stringOptional

          The first line of the address, such as the street name and number.

        • AddressLine2stringOptional

          The second line of the address, if there is one.

        • AptSuitNumstringOptional

          The apartment, suite, or building number.

        • CitystringOptional

          The city of the address.

        • CountryISO2stringRequired

          The two-character ISO country code of the individual recipient's country of residence, e.g. "US".

        • PostalCodestringOptional

          The postal or ZIP code of the address.

        • RegionstringOptional

          The state, province, or region of the address, e.g. "CA".

      • DateOfBirthobject

        The individual recipient's date of birth.

        Child parameters3
        • DaystringOptional

          The day of the month (1 to 31), as a numeric string, e.g. "15".

        • MonthstringOptional

          The month (1 to 12), as a numeric string, e.g. "08".

        • YearstringOptional

          The four-digit year, as a string, e.g. "1990".

      • EmailAddressstringRequired

        The individual recipient's primary contact email address.

      • EmailNotificationstringRequired

        Whether the individual recipient gets an email saying the account was created. Boolean as a string: "true" or "false".

        Allowed values: true, false.

      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you act on behalf of.

      • LegalFirstNamestringRequired

        The individual recipient's legal first name.

      • LegalLastNamestringRequired

        The individual recipient's legal last name.

      • MobilePhonestringOptional

        The individual recipient's primary mobile phone number. Don't include the country code: Xtrm determines it from the recipient's country.

      • TaxIdstringOptional

        The individual recipient's tax identification number, such as an SSN or national ID.

Response fields

  • CreateUserResponseobject

    Response wrapper.

    Child parameters1
    • CreateUserResultobject

      The result of the request.

      Child parameters3
      • UserIDstring

        The Xtrm account number of the new individual recipient, starting with PAT.

      • AccountIdentityLevelstring

        The identity verification level of the personal account: Draft, Basic, Standard or Advanced, from the lowest level to the highest. Draft means only the bare minimum details are on the account; Advanced means the identity profile is complete.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

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

POST/API/v4/Register/UpdateUser

Updates 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:

  1. Send the update with the new MobileNumber and MobileCountryISO2, and OTP set to "". Xtrm texts a six-digit one-time password (OTP) to the new mobile number and responds with HTTP 400, Success true and One Time Password sent to user. Please resubmit with One Time Password. in Errors. Nothing in the profile changes yet, so treat this response as the cue to ask the recipient for the code, not as a failure.
  2. Within 10 minutes, send the same request again, with every field and the same MobileNumber and MobileCountryISO2, plus the code in OTP. Xtrm saves the new number, applies the rest of the update and returns HTTP 200.

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.

Tip

To check the connection, call GetConnectedStatus. If you're not connected, call GetOTPAuthorizedVendor and then ValidateOTPAuthorizeVendor to connect.

Body parameters

  • UpdateUserobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters10
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you act on behalf of.

      • UserIdstringRequired

        The Xtrm account number of the individual recipient to update, starting with PAT.

      • LegalFirstNamestringRequired

        The individual recipient's legal first name.

      • LegalLastNamestringRequired

        The individual recipient's legal last name.

      • AddressobjectRequired

        The individual recipient's physical address.

        Child parameters7
        • CountryISO2stringRequired

          The two-character ISO country code of the address, e.g. "US".

        • AddressLine1stringOptional

          The primary line of the address, such as the street name and number.

        • AddressLine2stringOptional

          The secondary line of the address, such as a building name, floor, or care-of details.

        • AptSuitNumstringOptional

          The apartment, suite, or unit number.

        • CitystringOptional

          The city of the address.

        • PostalCodestringOptional

          The postal or ZIP code of the address.

        • RegionstringOptional

          The state, province, or region of the address, e.g. "CA".

      • DateOfBirthobject

        The individual recipient's date of birth.

        Child parameters3
        • DaystringOptional

          The day of the month (1 to 31), as a numeric string, e.g. "15".

        • MonthstringOptional

          The month (1 to 12), as a numeric string, e.g. "08".

        • YearstringOptional

          The four-digit year, as a string, e.g. "1990".

      • MobileCountryISO2stringOptional

        The two-character ISO country code for the new mobile phone number, e.g. "US". Required when you send MobileNumber.

      • MobileNumberstringOptional

        The 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 in MobileCountryISO2. Adding or changing the number takes two calls and a one-time password: see OTP. Leave MobileNumber out when you aren't changing the number.

      • OTPstringOptional

        The six-digit one-time password that Xtrm texts to the new mobile number, as a string. When you send MobileNumber, send OTP as "" on the first call, then resubmit the same request with the code within 10 minutes. Not needed when you leave out MobileNumber.

      • TaxIdstringOptional

        The individual recipient's tax identification number, such as an SSN or national ID.

Response fields

  • UpdateUserResponseobject

    Response wrapper.

    Child parameters1
    • UpdateUserResultobject

      The result of the request.

      Child parameters3
      • UserIDstring

        The Xtrm account number of the updated individual recipient, starting with PAT. null on the first call that adds or changes the mobile number.

      • AccountIdentityLevelstring

        The identity verification level of the personal account: Draft, Basic, Standard or Advanced, from the lowest level to the highest. Draft means only the bare minimum details are on the account; Advanced means the identity profile is complete. null on the first call that adds or changes the mobile number.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false). It's also true on the HTTP 400 response 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's null or an empty array [].

#Errors

MessageMeaning
400 · Invalid one-time passwordThe 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 missingYou 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

POST/API/v4/Beneficiary/GetPersonalBeneficiaries

Returns 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

  • GetPersonalBeneficiariesobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you act on behalf of.

      • PaginationobjectRequired

        Pagination settings for the list.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number to return, starting at "1". Integer as a string, e.g. "2" for the second page. "0" is rejected with HTTP 400.

        • RecordsToTakestringRequired

          The 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

  • GetPersonalBeneficiariesResponseobject

    Response wrapper.

    Child parameters1
    • GetPersonalBeneficiaryResultobject

      The result of the request.

      Child parameters3
      • Beneficiaryobject[]

        The individual recipients on this page of results.

        Child parameters7
        • AccountNostring

          The individual recipient's Xtrm account number, starting with PAT.

        • Namestring

          The individual recipient's full name.

        • Statestring

          The state, province, or region where the individual recipient lives, as saved on the account: for an account created with CreateUser, the Address.Region you sent, such as CA.

        • Countrystring

          The individual recipient's country, as its full name, e.g. United States of America.

        • Employerstring

          The name of the individual recipient's employer.

        • Emailstring

          The individual recipient's primary contact email address.

        • AccountIdentityLevelstring

          The identity verification level of the personal account: Draft, Basic, Standard or Advanced, from the lowest level to the highest. Draft means only the bare minimum details are on the account; Advanced means the identity profile is complete.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

      • PaginationTotalobject

        Pagination details for this page of results.

        Child parameters3
        • RecordsToSkipinteger

          The page number of these results, as sent in the request.

        • RecordsToTakeinteger

          The maximum number of results requested per page.

        • RecordsTotalinteger

          The 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