API reference

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.

#Search for existing company accounts

POST/API/v4/Beneficiary/CheckBeneficiaryExist

Searches 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

  • CheckBeneficiaryExistobjectRequired

    Wrapper object for the request.

    Child parameters1
    • requestobjectRequired

      Contains the request fields.

      Child parameters4
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you're making the call on behalf of.

      • CompanyNamestringOptional

        The 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 CompanyEmailDomain instead when you know it. Provide CompanyEmailDomain, CompanyName or both.

      • CompanyEmailDomainstringOptional

        The 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: with CompanyName as well, the search returns companies that match either one. Provide CompanyEmailDomain, CompanyName or both.

      • PaginationobjectOptional

        Controls which page of results is returned. If you send Pagination, include both RecordsToSkip and RecordsToTake. Without it, the call returns the first 30 matches.

        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

  • CheckBeneficiaryExistResponseobject

    Wrapper object for the response.

    Child parameters1
    • CheckBeneficiaryExistResultobject

      Contains the result of the search.

      Child parameters2
      • Beneficiaryobject[]

        The companies that match the search, sorted by name. Empty when nothing matches.

        Child parameters7
        • Namestring

          The registered name of the company.

        • AccountNumberstring

          The Xtrm account number of the matching company, starting with SPN.

        • Emailstring

          The company's account email: its master administrator's sign-in email. CompanyEmailDomain matches against it.

        • MasteradminFirstnamestring

          The first name of the company's master administrator.

        • MasteradminLastnamestring

          The last name of the company's master administrator.

        • Statusstring

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

        • AccountIdentityLevelstring

          The company's identity verification level: 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 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.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true or 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 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

POST/API/v4/Beneficiary/CreateBeneficiary

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

Body parameters

  • CreateBeneficiaryobjectRequired

    Wrapper object for the request.

    Child parameters1
    • RequestobjectRequired

      Contains the request fields.

      Child parameters5
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you're making the call on behalf of.

      • BeneficiaryCompanyNamestringRequired

        The legally registered name of the business recipient you're creating.

      • WebAddressstringOptional

        The primary website URL of the company.

      • BeneficiaryCompanyAdminDetailsobjectRequired

        The company's master administrator and the company's physical location.

        Child parameters9
        • AdminEmailstringRequired

          The primary email address of the company's master administrator.

        • EmailNotificationstringRequired

          Whether to send an account creation notification email to the administrator's email address. Boolean as a string: "true" or "false".

        • AdminFirstNamestringRequired

          The first name of the company's master administrator.

        • AdminLastNamestringRequired

          The last name of the company's master administrator.

        • AdminMobileNumberstringOptional

          The mobile phone number of the company's master administrator. Don't include the country code; it is determined from the country.

        • CountryISO2stringRequired

          The two-letter ISO country code of the company's location, e.g. US.

        • CitystringOptional

          The city where the company is physically located.

        • PostalCodestringOptional

          The postal or ZIP code of the company's physical address.

        • RegionstringOptional

          The state, province or region of the company's physical address, e.g. CA.

      • SalesProgramDetailsobject

        Partner and sales program details for the company.

        Child parameters5
        • PartnerAccountManagerstringOptional

          The full name of the partner's designated account manager.

        • OtherPartnerIDstringOptional

          An alternative identifier for the partner, if you don't use a Salesforce ID.

        • RegionstringOptional

          The operational or sales region associated with the partner profile.

        • PartnerLevelstringOptional

          The designated partner status, tier or sales level, e.g. Gold.

        • SalesforcePartnerIDstringOptional

          The Salesforce identifier of the partner.

Response fields

  • CreateBeneficiaryResponseobject

    Wrapper object for the response.

    Child parameters1
    • CreateBeneficiaryResultobject

      Contains the new business recipient's details.

      Child parameters5
      • BeneficiaryIDstring

        The Xtrm account number generated for the new business recipient, starting with SPN.

      • AccountIdentityLevelstring

        The company's identity verification level: 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 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.

      • ClientIDstring

        The client ID of your pseudo credentials for the new company. The example shows a placeholder value.

      • SecretKeystring

        The secret of your pseudo credentials for the new company. Use it with ClientID to request an access token that acts as the new company. The example shows a placeholder value.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true or 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: 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

POST/API/v4/Beneficiary/UpdateBeneficiary

Updates 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

  • UpdateBeneficiaryobjectRequired

    Wrapper object for the request.

    Child parameters1
    • RequestobjectRequired

      Contains the request fields.

      Child parameters6
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you're making the call on behalf of.

      • BeneficiaryIDstringRequired

        The Xtrm account number of the business recipient you're updating, starting with SPN.

      • BeneficiaryCompanyNamestringRequired

        The legally registered name of the business recipient.

      • WebAddressstring

        The primary website URL of the company. Optional, but send the current value even if it isn't changing: an omitted WebAddress clears the saved website.

      • BeneficiaryCompanyAdminDetailsobjectRequired

        The company's master administrator and the company's physical location.

        Child parameters6
        • AdminFirstNamestringRequired

          The first name of the company's master administrator.

        • AdminLastNamestringRequired

          The last name of the company's master administrator.

        • CitystringRequired

          The city where the company is physically located.

        • CountryISO2stringRequired

          The two-letter ISO country code of the company's location, e.g. US.

        • RegionstringRequired

          The state, province or region of the company's physical address, e.g. CA.

        • PostalCodestringRequired

          The postal or ZIP code of the company's physical address.

      • SalesProgramDetailsobjectRequired

        Partner and sales program details for the company.

        Child parameters5
        • PartnerAccountManagerstringOptional

          The full name of the partner's designated account manager.

        • OtherPartnerIDstringRequired

          An alternative identifier for the partner, if you don't use a Salesforce ID.

        • RegionstringRequired

          The operational or sales region associated with the partner profile.

        • PartnerLevelstringOptional

          The designated partner status, tier or sales level, e.g. Gold.

        • SalesforcePartnerIDstringOptional

          The Salesforce identifier of the partner.

Response fields

  • UpdateBeneficiaryResponseobject

    Wrapper object for the response.

    Child parameters1
    • UpdateBeneficiaryResultobject

      Contains the updated business recipient's details.

      Child parameters3
      • BeneficiaryIDstring

        The Xtrm account number of the updated business recipient, starting with SPN.

      • AccountIdentityLevelstring

        The company's identity verification level: 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 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.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true or 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 a business recipient · List business recipients · Search for existing company accounts · List countries · List regions for a country ID

#List business recipients

POST/API/v4/Beneficiary/GetBeneficiaries

Returns 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

  • GetBeneficiariesobjectRequired

    Wrapper object for the request.

    Child parameters1
    • requestobjectRequired

      Contains the request fields.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you're making the call on behalf of.

      • PaginationobjectRequired

        Controls which page of results is returned.

        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

  • GetBeneficiariesResponseobject

    Wrapper object for the response.

    Child parameters1
    • BeneficiaryResultobject

      Contains the list of business recipients.

      Child parameters3
      • Beneficiariesobject

        Container for the business recipient records.

        Child parameters1
        • BeneficiaryDetailobject[]

          The business recipient records on this page.

          Child parameters9
          • BeneficiaryCompanyNamestring

            The legally registered name of the business recipient.

          • BeneficiaryContactstring

            The business recipient's primary contact name.

          • PartnerAccountManagerstring

            The full name of the partner's designated account manager.

          • BeneficiaryIDstring

            The business recipient's Xtrm account number, starting with SPN.

          • BeneficiarySalesforceIdstring

            The business recipient's Salesforce identifier.

          • OtherPartnerIDstring

            The partner level saved from SalesProgramDetails.PartnerLevel when you created or updated the company, such as Gold. Despite its name, this field holds the partner level, not the OtherPartnerID you sent.

          • Regionstring

            The sales region saved from SalesProgramDetails.Region when you created or updated the company, such as CA. It isn't part of the company's address.

          • BeneficiaryEmailstring

            The business recipient's primary contact email address.

          • BeneficiaryAccountIdentityLevelstring

            The company's identity verification level: 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 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.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true or false).

        • Errorsstring[]

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

      • PaginationTotalobject

        Pagination details for the returned 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: 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

POST/API/v4/Beneficiary/GetEntities

Returns 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

  • GetEntitiesobjectRequired

    Wrapper object for the request.

    Child parameters1
    • requestobjectRequired

      Contains the request fields.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company you're making the call on behalf of.

      • UserIDstringRequired

        The SPN account number of the company whose entities you want: your own company or a company connected to yours.

      • PaginationobjectRequired

        Controls which page of results is returned.

        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 maximum number of results to return per page. Integer as a string, e.g. "25".

Response fields

  • GetEntitiesResponseobject

    Wrapper object for the response.

    Child parameters1
    • EntitiesResultobject

      Contains the list of entities.

      Child parameters3
      • Entitiesobject

        Container for the entity records.

        Child parameters1
        • EntityDetailsobject[]

          The entity records on this page.

          Child parameters5
          • EntityIdinteger

            The unique internal system identifier of the entity.

          • EntityNamestring

            The registered name of the entity.

          • EntityDescriptionstring

            A brief description or categorization of the entity. May be an empty string.

          • IsPrimeEntityboolean

            Whether this is the account's primary entity (true or false).

          • TotalUsersinteger

            The total number of people assigned to or associated with the entity.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true or false).

        • Errorsstring[]

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

      • PaginationTotalobject

        Pagination details for the returned 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: List business recipients · Create a business recipient's wallet · Link a bank account to a recipient · Link a card to a recipient