Business recipients
A business recipient is a company with an Xtrm account, identified by an account number that starts with SPN. Use these endpoints to check whether a company already has an Xtrm account, create and update business recipients, and list your business recipients and a company's entities.
Every request identifies your company in IssuerAccountNumber: the SPN of the company tied to your API credentials, or of the company you act for when you use pseudo credentials. Business recipients are reviewed with identity and sanctions checks (KYC), so the information you submit must be real and accurate.
CheckBeneficiaryExist, GetBeneficiaries and GetEntities take a Pagination object (RecordsToSkip, RecordsToTake); GetBeneficiaries and GetEntities also return a PaginationTotal object that includes RecordsTotal.
- POST
/API/v4/Beneficiary/CheckBeneficiaryExistSearch for existing company accounts - POST
/API/v4/Beneficiary/CreateBeneficiaryCreate a business recipient - POST
/API/v4/Beneficiary/UpdateBeneficiaryUpdate a business recipient - POST
/API/v4/Beneficiary/GetBeneficiariesList business recipients - POST
/API/v4/Beneficiary/GetEntitiesList your organization's entities
#Search for existing company accounts
/API/v4/Beneficiary/CheckBeneficiaryExistSearches every company account on Xtrm, not only yours, by company email domain or company name, and returns minimal information about each match. Companies often have an Xtrm account already, so search before you create one with CreateBeneficiary.
When you know the company's email domain, search with CompanyEmailDomain on its own. Send the domain (acmecorp.com) or any address at it ([email protected]): Xtrm uses only the part after the @. It matches companies whose account email, the master administrator's sign-in email, is at that domain, so a company's own domain usually returns just that company. A shared domain can return several companies, and the match is on text, so acmecorp.com also returns a company at acmecorp.com.au. Check Email and Name before you use an AccountNumber.
CompanyName returns every company whose name contains the text, in any case, so a name search can return several companies, up to 30 per page unless you set Pagination. Xtrm uses the first 50 characters of the name. If you send both CompanyName and CompanyEmailDomain, you get the companies that match either one, so send the domain alone when you have it.
Each result has the company's Name, AccountNumber (SPN…), Email, master administrator, Status (Active, Email not verified or Account pending approval) and AccountIdentityLevel. Results are sorted by name, and the response has no total count of matches. You don't need a connection to a company to find it or to see its identity verification level.
Note
Send CompanyEmailDomain, CompanyName or both. At least one is required. When you know the company's email domain, send it on its own: with both fields, the search returns companies that match either one.
Body parameters
CheckBeneficiaryExistobjectRequiredWrapper object for the request.
Child parameters1
requestobjectRequiredContains the request fields.
Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the company account associated with the API credentials you're using. If you use pseudo credentials, this is theSPNof the company you're making the call on behalf of.CompanyNamestringOptionalThe registered name of the company to search for, or part of it, 3 to 100 characters. Matches every company whose name contains the text, in any case; Xtrm uses the first 50 characters. Send
CompanyEmailDomaininstead when you know it. ProvideCompanyEmailDomain,CompanyNameor both.CompanyEmailDomainstringOptionalThe company's email domain, such as
acmecorp.com, 3 to 100 characters. Any address at the domain works too, such as[email protected]: Xtrm uses only the part after the@. Matches companies whose account email is at the domain. We recommend sending it on its own: withCompanyNameas well, the search returns companies that match either one. ProvideCompanyEmailDomain,CompanyNameor both.PaginationobjectOptionalControls which page of results is returned. If you send
Pagination, include bothRecordsToSkipandRecordsToTake. Without it, the call returns the first 30 matches.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
CheckBeneficiaryExistResponseobjectWrapper object for the response.
Child parameters1
CheckBeneficiaryExistResultobjectContains the result of the search.
Child parameters2
Beneficiaryobject[]The companies that match the search, sorted by name. Empty when nothing matches.
Child parameters7
NamestringThe registered name of the company.
AccountNumberstringThe Xtrm account number of the matching company, starting with
SPN.EmailstringThe company's account email: its master administrator's sign-in email.
CompanyEmailDomainmatches against it.MasteradminFirstnamestringThe first name of the company's master administrator.
MasteradminLastnamestringThe last name of the company's master administrator.
StatusstringThe account's status:
Active,Email not verifiedorAccount pending approval. The search returns only accounts in one of these statuses.AccountIdentityLevelstringThe company's identity verification level:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account.Advancedmeans the profile is 100% complete, including the identity documents uploaded in the Xtrm web app, which a company needs, with an approved advanced profile, before Xtrm unlocks funding for its account.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
trueorfalse).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 a business recipient · List business recipients · Get the connection status of an account · Send a connection one-time password · Check whether an individual recipient exists
#Create a business recipient
/API/v4/Beneficiary/CreateBeneficiaryCreates a business recipient: a company account with its master administrator, location and, optionally, sales program details. A company account you create through the API is active straight away, and it's connected to your company, which also adds it to your business recipients (GetBeneficiaries). If you call it with a client company's pseudo credentials, the new company is connected to the client company and to your platform. See Connections and manager services. A batch payment pays existing accounts only, so create a company before you submit the batch that pays it. Search first with CheckBeneficiaryExist, so you don't create a second account for a company that already has one.
The response contains the new company's account number (BeneficiaryID, starting with SPN), its AccountIdentityLevel, and ClientID and SecretKey: your pseudo credentials for the new company. Use them to request an access token that acts as the new company, with its SPN as IssuerAccountNumber. Keep them on your server, as you keep your own. If you call with a client company's pseudo credentials, the pair is issued to that client company. Pseudo credentials require manager services, which Xtrm turns on for your company. See Pseudo credentials.
You can pay the new company straight away. Before it can fund its own wallets and pay recipients, it needs to reach Advanced, and part of that onboarding happens in the Xtrm web app, because no API call uploads documents. Its documents are a government-issued photo ID for its administrator and, for a private company, a company tax document such as a W-9 for a US company. The company uploads them under Identity > Identity Documents, or your company uploads them for it with the Identity Documents manager service, which Xtrm turns on for your company. Then the company, or your company for it, submits its advanced profile for Xtrm to review. See Complete the advanced profile.
Make sure the information you submit is real and accurate: once created, business recipients are reviewed with identity and sanctions checks. Set EmailNotification to "true" to send an account creation email to the administrator's email address.
Important
Don't create test companies or test email addresses on production servers. Every business recipient you create is reviewed with identity and sanctions checks.
Body parameters
CreateBeneficiaryobjectRequiredWrapper object for the request.
Child parameters1
RequestobjectRequiredContains the request fields.
Child parameters5
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the company account associated with the API credentials you're using. If you use pseudo credentials, this is theSPNof the company you're making the call on behalf of.BeneficiaryCompanyNamestringRequiredThe legally registered name of the business recipient you're creating.
WebAddressstringOptionalThe primary website URL of the company.
BeneficiaryCompanyAdminDetailsobjectRequiredThe company's master administrator and the company's physical location.
Child parameters9
AdminEmailstringRequiredThe primary email address of the company's master administrator.
EmailNotificationstringRequiredWhether to send an account creation notification email to the administrator's email address. Boolean as a string:
"true"or"false".AdminFirstNamestringRequiredThe first name of the company's master administrator.
AdminLastNamestringRequiredThe last name of the company's master administrator.
AdminMobileNumberstringOptionalThe mobile phone number of the company's master administrator. Don't include the country code; it is determined from the country.
CountryISO2stringRequiredThe two-letter ISO country code of the company's location, e.g.
US.CitystringOptionalThe city where the company is physically located.
PostalCodestringOptionalThe postal or ZIP code of the company's physical address.
RegionstringOptionalThe state, province or region of the company's physical address, e.g.
CA.
SalesProgramDetailsobjectPartner and sales program details for the company.
Child parameters5
PartnerAccountManagerstringOptionalThe full name of the partner's designated account manager.
OtherPartnerIDstringOptionalAn alternative identifier for the partner, if you don't use a Salesforce ID.
RegionstringOptionalThe operational or sales region associated with the partner profile.
PartnerLevelstringOptionalThe designated partner status, tier or sales level, e.g.
Gold.SalesforcePartnerIDstringOptionalThe Salesforce identifier of the partner.
Response fields
CreateBeneficiaryResponseobjectWrapper object for the response.
Child parameters1
CreateBeneficiaryResultobjectContains the new business recipient's details.
Child parameters5
BeneficiaryIDstringThe Xtrm account number generated for the new business recipient, starting with
SPN.AccountIdentityLevelstringThe company's identity verification level:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account.Advancedmeans the profile is 100% complete, including the identity documents uploaded in the Xtrm web app, which a company needs, with an approved advanced profile, before Xtrm unlocks funding for its account.ClientIDstringThe client ID of your pseudo credentials for the new company. The example shows a placeholder value.
SecretKeystringThe secret of your pseudo credentials for the new company. Use it with
ClientIDto request an access token that acts as the new company. The example shows a placeholder value.OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
trueorfalse).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: Search for existing company accounts · Update a business recipient · List business recipients · Submit a company advanced profile · Create a business recipient's wallet · List countries · List regions for a country ID
#Update a business recipient
/API/v4/Beneficiary/UpdateBeneficiaryUpdates an existing business recipient, identified by its SPN account number in BeneficiaryID. Your company needs a connection to the company, which it has with every company it creates with CreateBeneficiary. See Connections and manager services. You send the company name and website, the master administrator's name, the company's physical address and the sales program details.
The response returns the company's BeneficiaryID and its AccountIdentityLevel.
Business recipients are reviewed with identity and sanctions checks, so make sure the information you submit is real and accurate.
Body parameters
UpdateBeneficiaryobjectRequiredWrapper object for the request.
Child parameters1
RequestobjectRequiredContains the request fields.
Child parameters6
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the company account associated with the API credentials you're using. If you use pseudo credentials, this is theSPNof the company you're making the call on behalf of.BeneficiaryIDstringRequiredThe Xtrm account number of the business recipient you're updating, starting with
SPN.BeneficiaryCompanyNamestringRequiredThe legally registered name of the business recipient.
WebAddressstringThe primary website URL of the company. Optional, but send the current value even if it isn't changing: an omitted
WebAddressclears the saved website.BeneficiaryCompanyAdminDetailsobjectRequiredThe company's master administrator and the company's physical location.
Child parameters6
AdminFirstNamestringRequiredThe first name of the company's master administrator.
AdminLastNamestringRequiredThe last name of the company's master administrator.
CitystringRequiredThe city where the company is physically located.
CountryISO2stringRequiredThe two-letter ISO country code of the company's location, e.g.
US.RegionstringRequiredThe state, province or region of the company's physical address, e.g.
CA.PostalCodestringRequiredThe postal or ZIP code of the company's physical address.
SalesProgramDetailsobjectRequiredPartner and sales program details for the company.
Child parameters5
PartnerAccountManagerstringOptionalThe full name of the partner's designated account manager.
OtherPartnerIDstringRequiredAn alternative identifier for the partner, if you don't use a Salesforce ID.
RegionstringRequiredThe operational or sales region associated with the partner profile.
PartnerLevelstringOptionalThe designated partner status, tier or sales level, e.g.
Gold.SalesforcePartnerIDstringOptionalThe Salesforce identifier of the partner.
Response fields
UpdateBeneficiaryResponseobjectWrapper object for the response.
Child parameters1
UpdateBeneficiaryResultobjectContains the updated business recipient's details.
Child parameters3
BeneficiaryIDstringThe Xtrm account number of the updated business recipient, starting with
SPN.AccountIdentityLevelstringThe company's identity verification level:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account.Advancedmeans the profile is 100% complete, including the identity documents uploaded in the Xtrm web app, which a company needs, with an approved advanced profile, before Xtrm unlocks funding for its account.OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
trueorfalse).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 a business recipient · List business recipients · Search for existing company accounts · List countries · List regions for a country ID
#List business recipients
/API/v4/Beneficiary/GetBeneficiariesReturns a paginated list of your company's business recipients: every company your company created or connected to, and every company it paid in a batch once that payment completed. Each record includes the company name, contact name and email, SPN account number, identity verification level, Salesforce ID and region, and its partner account manager and other partner ID.
Use Pagination to page through the results. PaginationTotal.RecordsTotal in the response gives the total number of records available.
Body parameters
GetBeneficiariesobjectRequiredWrapper object for the request.
Child parameters1
requestobjectRequiredContains the request fields.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the company account associated with the API credentials you're using. If you use pseudo credentials, this is theSPNof the company you're making the call on behalf of.PaginationobjectRequiredControls which page of results is returned.
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
GetBeneficiariesResponseobjectWrapper object for the response.
Child parameters1
BeneficiaryResultobjectContains the list of business recipients.
Child parameters3
BeneficiariesobjectContainer for the business recipient records.
Child parameters1
BeneficiaryDetailobject[]The business recipient records on this page.
Child parameters9
BeneficiaryCompanyNamestringThe legally registered name of the business recipient.
BeneficiaryContactstringThe business recipient's primary contact name.
PartnerAccountManagerstringThe full name of the partner's designated account manager.
BeneficiaryIDstringThe business recipient's Xtrm account number, starting with
SPN.BeneficiarySalesforceIdstringThe business recipient's Salesforce identifier.
OtherPartnerIDstringThe partner level saved from
SalesProgramDetails.PartnerLevelwhen you created or updated the company, such asGold. Despite its name, this field holds the partner level, not theOtherPartnerIDyou sent.RegionstringThe sales region saved from
SalesProgramDetails.Regionwhen you created or updated the company, such asCA. It isn't part of the company's address.BeneficiaryEmailstringThe business recipient's primary contact email address.
BeneficiaryAccountIdentityLevelstringThe company's identity verification level:
Draft,Basic,StandardorAdvanced, from the lowest level to the highest.Draftmeans only the bare minimum details are on the account.Advancedmeans the profile is 100% complete, including the identity documents uploaded in the Xtrm web app, which a company needs, with an approved advanced profile, before Xtrm unlocks funding for its account.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
trueorfalse).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
[""], an array holding one empty string, so decide withSuccess.
PaginationTotalobjectPagination details for the returned 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: Create a business recipient · Update a business recipient · Search for existing company accounts · List your organization's entities · List a recipient's wallets · List individual recipients
#List your organization's entities
/API/v4/Beneficiary/GetEntitiesReturns a paginated list of entities for the company in UserID: your own company or a company connected to yours. Each entity includes its ID, name, description, whether it is the prime entity, and the number of people assigned to or associated with it (TotalUsers).
Use Pagination to page through the results. PaginationTotal.RecordsTotal in the response gives the total number of records available.
Body parameters
GetEntitiesobjectRequiredWrapper object for the request.
Child parameters1
requestobjectRequiredContains the request fields.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the company account associated with the API credentials you're using. If you use pseudo credentials, this is theSPNof the company you're making the call on behalf of.UserIDstringRequiredThe
SPNaccount number of the company whose entities you want: your own company or a company connected to yours.PaginationobjectRequiredControls which page of results is returned.
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 maximum number of results to return per page. Integer as a string, e.g.
"25".
Response fields
GetEntitiesResponseobjectWrapper object for the response.
Child parameters1
EntitiesResultobjectContains the list of entities.
Child parameters3
EntitiesobjectContainer for the entity records.
Child parameters1
EntityDetailsobject[]The entity records on this page.
Child parameters5
EntityIdintegerThe unique internal system identifier of the entity.
EntityNamestringThe registered name of the entity.
EntityDescriptionstringA brief description or categorization of the entity. May be an empty string.
IsPrimeEntitybooleanWhether this is the account's primary entity (
trueorfalse).TotalUsersintegerThe total number of people assigned to or associated with the entity.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
trueorfalse).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
[""], an array holding one empty string, so decide withSuccess.
PaginationTotalobjectPagination details for the returned 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: List business recipients · Create a business recipient's wallet · Link a bank account to a recipient · Link a card to a recipient