Guide

Complete the advanced profile

Before Xtrm unlocks funding for a company, it needs to know who it's dealing with. The advanced profile is how you tell it: one application that covers the company, the person who signs for it and the people who own it, which Xtrm reviews for identity and sanctions checks (KYC/KYB).

Submit it for your own company, or, as a managing platform, for a client company that's connected to yours. This guide does the second: your company, SPN1111222, onboards its client company Contoso Ltd, SPN7777555. You'll complete the company's Identity profile and upload its documents in the Xtrm web app, submit the advanced profile, follow Xtrm's review until it's Approved and read the profile back. Once the profile is approved and the company's identity verification level (IDL) is at 100%, which the API reports as AccountIdentityLevel Advanced, Xtrm unlocks funding for the company's account. Every sample runs against the sandbox.

Documents go through the web app

No API call uploads files, so onboarding a company isn't API-only. Its documents are uploaded in the Xtrm web app, by the company itself or, for a client company, by your platform as a manager service. Step 1 shows both.

#Before you begin

  • Sandbox credentials. Your client ID and secret from Settings → Integrations → Get Credentials in the sandbox web app, with your IP addresses approved by Xtrm. See Sandbox & environments.
  • An access token in the XTRM_ACCESS_TOKEN environment variable. See Authentication.
  • Your company's account number, the SPN that owns your API credentials (SPN1111222 in the samples). You send it as IssuerAccountNumber. If you use pseudo credentials, send the SPN of the company you act on behalf of.
  • The account number of the company the profile is for, sent as BeneficiaryAccountNumber: your own SPN, or the SPN of a client company (SPN7777555 in the samples). For a client company, your company needs a connection to it, which it has with every company it creates with CreateBeneficiary. Check one with GetConnectedStatus, and see Connections and manager services for how connections work.
  • The company's details: legal structure, website, tax identification number, headquarters and incorporation location, and, for a company outside the US or a US company that pays internationally, its industry, the purpose of its transactions and its expected activity. You also need personal details for each person who owns 26% or more of the company and, for an international profile, for an authorized contact.
  • The company's documents: a government-issued photo ID for its administrator and, for a private company, a company tax document that shows its tax ID, such as a W-9 for a US company. You upload them in the Xtrm web app in step 1.
  • Access to the Xtrm web app. For your own company, you sign in to its account. For a client company, either the company signs in to its own account and uploads its documents, or your company uploads them for it with the Identity Documents manager service, which Xtrm turns on for your company. See Manager services.

#How the profile is organized

The profile has three sections: business entity, authorized contact and ownership information. The authorized contact is the company's director or signatory, so there's no separate director section. Which fields a company must complete depends on whether its profile is international:

  • An international profile is the profile of every company registered outside the US, and of a US company that sends "Payments_Type": "International". It needs the business entity details, including the company's industry and expected activity, the authorized contact's details and address, and the ownership information.
  • A USA Only profile is the profile of a US company that sends "Payments_Type": "USA Only". A company that pays only in the US has a lighter onboarding: its profile needs the business entity details and IsPublicallyTraded. The authorized contact, the industry, the purpose of transactions and the expected activity are required only in an international profile.

In either kind of profile, a company that isn't publicly traded lists each person who owns 26% or more of it.

In the request, the sections are objects inside AdvancedProfile.request:

ObjectWhat it holdsWho completes it
BusinessEntityInformationLegal structure, website, tax identification number, headquarters and incorporation location, the company's industry, the purpose of its transactions and its expected activity, and, optionally, the authorized contact's government-issued identification documentEvery company. The industry, purpose and expected activity are required in an international profile.
AuthorizedContactInformationThe person who represents the company: name, job title, email address, business phone, date of birth, citizenship and addressAn international profile. A USA Only profile doesn't need it.
OwnerInformationIsPublicallyTraded (yes or no), IsEligibleOwnership and the Owners listEvery company sends the object, because IsPublicallyTraded is required. Owners lists each person who owns 26% or more of a company that isn't publicly traded.

Some fields take values from Xtrm's lookups, such as two-character country codes and company types. Field values lists which lookup fills which field.

#Submit and track the profile

One visit to the Xtrm web app and three API calls take the company from its documents to an approved profile:

StepWhereWhat you get
1The Xtrm web appThe company's Identity profile is complete, with its documents on file, and its level is Advanced.
2CompanyAdvancedProfileThe submission is saved and goes to Xtrm for review.
3CompanyAdvancedProfileStatusThe review status, until it's Approved.
4GetCompanyAdvancedProfileDetailsThe profile as Xtrm holds it.
  1. Complete the Identity profile in the web app

    To reach Advanced, the company needs its Identity profile 100% complete in the Xtrm web app: its business tax ID, its address and its documents. No API call uploads files, so this step always happens in the web app.

    The documents depend on the company type you choose when you upload, Private unless you change it:

    • A government-issued photo ID for the company's administrator. Every company needs one.
    • A company tax document that shows the company's tax ID, such as a W-9 or SS-4 for a US company. A private company needs one, and a public company doesn't.

    Other document types are needed only if Xtrm asks for them. Upload the documents in one of two ways:

    • For your own company: open Identity in the web app's menu, select Identity Documents, then Upload Identity Documents, and add each document with its type. For the photo ID, and for a US private company's tax document, choose Continue and follow the verification steps instead of choosing a file.
    • For a client company: the client company can upload them itself, from its own account, the same way. Or your company uploads them for it: open Contacts > Company Contacts, open the client company's profile and choose Identity Documents in its Connected Manager Services menu. Identity Profile in the same menu edits the company's organization details, such as its business tax ID and address. Uploading a connected company's documents is a manager service, so Xtrm has to turn it on for your company, and the admin who uploads needs the Master Admin or Controller role and the Connected Manager Services permission. Submitting the profile through the API in step 2 needs only the connection. See Manager services.

    Each file can be up to 20 MB, as JPEG, BMP, PNG, PDF, DOC or DOCX.

    Once the Identity profile is complete, the company's AccountIdentityLevel reads Advanced. For a client company, CheckBeneficiaryExist returns it. Finish this step before you submit the profile: in the web app, the Advanced Services Application opens only once the Identity profile is 100% complete.

  2. Submit the profile

    With the Identity profile complete, build the advanced profile from the company's details and the field values from the lookups, and submit it with CompanyAdvancedProfile. The sample is an international profile for Contoso Ltd, a US company: it sends "Payments_Type": "International", so it includes every field an international profile needs. It also sends the company's expected volumes, the optional identification document and one owner, who owns 100% of the company.

    What each part needs:

    • Root of request: IssuerAccountNumber, BeneficiaryAccountNumber and Country_Of_Registration_Code2 are required. Payments_Type is required for a company registered in the US and must be USA Only or International. For a company registered anywhere else, Xtrm sets it to International, whatever you send.
    • BusinessEntityInformation: every profile needs Company_Type, Website, Tax_Identification_Number, Country_Of_Incorporation_Code2, Region_Of_Incorporation_Code2, Address_Line_1, City, Region_Code2, Postal_Code and Country_Code2. An international profile also needs Industry_Classification, Purpose_Of_Transactions and the expected activity: Expected_Currencies, Countries_Sending_To and Countries_Receiving_From, as comma-separated strings ("USD,CAD,GBP" for currencies, "US, GB" for countries). Optional fields add a DBA name (Fictitious_Name), more address lines (Address_Line_2, Address_Line_3), the identification document (Identification_Type, Identification_Number), and Expected_Annual_Volume and Expected_Transaction_Amount as numeric strings.
    • AuthorizedContactInformation: an international profile needs every field: First_Name, Last_Name, Job_Title, Email_Address, Business_Phone (digits only, such as 2065551234), Date_Of_Birth (mm/dd/yyyy), Citizenship, and the address in Address_Line_1, City, Region_Code2, Postal_Code and Country_Code2. A USA Only profile doesn't need the authorized contact.
    • OwnerInformation: IsPublicallyTraded (yes or no) is required. For a publicly traded company (yes), send Ticker_Symbol, which an international profile requires; Xtrm doesn't keep Owners for a publicly traded company. For a company that isn't publicly traded (no), set IsEligibleOwnership to true, a JSON boolean, when one or more people own 26% or more of the company, and list those owners in Owners. Each owns 26% or more and together they can't own more than 100%, so a profile lists one to three owners. Xtrm reads Owners only when IsEligibleOwnership is true, so with false, or without the field, the list isn't saved.
    • Each owner: Percentage_Owned is the share the owner holds, as a whole number in a string from "26" to "100", and together the owners can't own more than 100%. In an international profile, each owner also needs First_Name, Last_Name, Job_Title, Date_of_Birth (mm/dd/yyyy), Citizenship, and the address in Address_Line_1, City, Region_Code2, Postal_Code and Country_Code2. Middle_Name and Email_Address are optional.
    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "AdvancedProfile": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryAccountNumber": "SPN7777555",
          "Country_Of_Registration_Code2": "US",
          "Payments_Type": "International",
          "BusinessEntityInformation": {
            "Company_Type": "C Corporation",
            "Industry_Classification": "Software Publishers",
            "Website": "https://www.contoso.com",
            "Tax_Identification_Number": "12-3456789",
            "Identification_Type": "Passport",
            "Identification_Number": "XX123456",
            "Country_Of_Incorporation_Code2": "US",
            "Region_Of_Incorporation_Code2": "DE",
            "Address_Line_1": "1 Contoso Way",
            "City": "Seattle",
            "Region_Code2": "WA",
            "Postal_Code": "98101",
            "Country_Code2": "US",
            "Purpose_Of_Transactions": "Business to Business Vendor Payments",
            "Expected_Currencies": "USD,CAD,GBP",
            "Expected_Annual_Volume": "500000.00",
            "Expected_Transaction_Amount": "5000.00",
            "Countries_Sending_To": "US, GB",
            "Countries_Receiving_From": "US, GB"
          },
          "AuthorizedContactInformation": {
            "First_Name": "Priya",
            "Last_Name": "Shah",
            "Job_Title": "Director",
            "Email_Address": "[email protected]",
            "Business_Phone": "2065551234",
            "Date_Of_Birth": "04/12/1982",
            "Citizenship": "US",
            "Address_Line_1": "1 Contoso Way",
            "City": "Seattle",
            "Region_Code2": "WA",
            "Postal_Code": "98101",
            "Country_Code2": "US"
          },
          "OwnerInformation": {
            "IsPublicallyTraded": "no",
            "IsEligibleOwnership": true,
            "Owners": [
              {
                "First_Name": "Priya",
                "Last_Name": "Shah",
                "Job_Title": "Owner",
                "Percentage_Owned": "100",
                "Email_Address": "[email protected]",
                "Date_of_Birth": "04/12/1982",
                "Citizenship": "US",
                "Address_Line_1": "1 Contoso Way",
                "City": "Seattle",
                "Region_Code2": "WA",
                "Postal_Code": "98101",
                "Country_Code2": "US"
              }
            ]
          }
        }
      }
    }'

    Copy the field names exactly

    The date-of-birth field is Date_Of_Birth in AuthorizedContactInformation but Date_of_Birth in each owner, and IsPublicallyTraded is spelled as shown. The body's root key is AdvancedProfile, not the operation name.

    Response
    {
      "AdvancedProfileResponse": {
        "AdvancedProfileResult": {
          "BeneficiaryID": "SPN7777555",
          "Message": "Advanced Profile Submitted Successfully",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Check OperationStatus.Success. On success, Message confirms the submission with Advanced Profile Submitted Successfully. If the profile is missing something, the call fails instead, and OperationStatus.Errors lists what to fix (see What can go wrong).

    To correct the profile later, submit the whole profile again with the same call: the new submission replaces the saved one.

    Keep: BeneficiaryID, the SPN of the company whose profile was submitted.

  3. Poll the application status

    CompanyAdvancedProfileStatus returns the status of the application in Message: one of Submitted, Pending, Approved or Deactive. Send your IssuerAccountNumber and the company's SPN as BeneficiaryAccountNumber.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "AdvancedProfileStatus": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryAccountNumber": "SPN7777555"
        }
      }
    }'
    Response
    {
      "AdvancedProfileStatusResponse": {
        "AdvancedProfileStatusResult": {
          "BeneficiaryID": "SPN7777555",
          "Message": "Approved",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Submitted and Pending mean the application is still with Xtrm for review. Xtrm usually reviews a USA Only profile in 1 to 2 days and an international profile in 5 to 7 days. Xtrm's webhooks cover batch payments only, so poll on a schedule, such as a few times a day, not in a tight loop, until Message is Approved. If you get Deactive, stop polling and contact [email protected].

    If the company has no profile on file, the call fails with HTTP 400 and Please complete company advanced profile to view the status.

    Keep: Message, the current status.

  4. Read back the submitted profile

    GetCompanyAdvancedProfileDetails returns the full application for your own company or a company connected to yours. It takes the same two account numbers as the status call.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "AdvancedProfileDetails": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryAccountNumber": "SPN7777555"
        }
      }
    }'

    The response uses the request's sections and adds the application Status. This excerpt shows a few fields from each section:

    Response (excerpt)
    {
      "AdvancedProfileDetailsResponse": {
        "AdvancedProfileDetailsResult": {
          "BeneficiaryAccountNumber": "SPN7777555",
          "Country_Of_Registration_Code2": "US",
          "Payments_Type": "International",
          "Status": "Approved",
          "BusinessEntityInformation": {
            "Legal_Company_Name": "Contoso Ltd",
            "Website": "https://www.contoso.com",
            "Company_Type": "C Corporation",
            "Industry_Classification": "Software Publishers",
            "Country_Of_Incorporation_Code2": "US",
            "Region_Of_Incorporation_Code2": "DE",
            "Purpose_Of_Transactions": "Business to Business Vendor Payments",
            "Expected_Annual_Volume": "500000.00",
            "Expected_Per_Transaction_Amount": "5000.00"
          },
          "AuthorizedContactInformation": {
            "Job_Title": "Director",
            "Job_Title_Other": "",
            "First_Name": "Priya",
            "Last_Name": "Shah",
            "Email_Address": "[email protected]",
            "Citizenship": "US"
          },
          "OwnerInformation": {
            "IsPublicallyTraded": "No",
            "Owners": [
              {
                "First_Name": "Priya",
                "Last_Name": "Shah",
                "Job_Title": "Owner",
                "Percentage_Owned": "100"
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    A few fields differ from what you sent:

    • The expected amount per transaction comes back as Expected_Per_Transaction_Amount; the request field is Expected_Transaction_Amount.
    • IsPublicallyTraded can come back capitalized, such as "No". Xtrm accepts yes and no in any capitalization, so compare the value without regard to case.
    • The response adds Legal_Company_Name, the legal name on the company's Xtrm account. Job_Title_Other holds the authorized contact's job title when Job_Title is Other; it's empty here.

    The details call answers even before a profile is submitted, with the details on the company's Xtrm account, and its Status can be empty or null even once Xtrm has approved the profile. Take the review status from the status call in step 3.

    Keep: the profile itself, if you show it in your product or compare it with your records.

#Field values

Six lookups return values that profile fields take. Each is a POST with the body shown, and the lists change rarely, so we recommend caching them rather than calling them for every profile. Use these lookups, not GetCountry and GetState: in GetCountry, CountryCode holds the three-character code (USA). The last column says whether Xtrm checks the field against the list when you submit the profile.

Lookup and bodyFields it fillsChecked
GetAdvancedContactCountry, {}Country_Of_Registration_Code2, Country_Of_Incorporation_Code2, every Country_Code2 and Citizenship: the two-character CountryCode, such as USYes, for the registration, incorporation and business countries, and the authorized contact's country in an international profile
GetAdvancedContactState, {"AdvancedContactState": {"request": {"CountryCode": "US"}}}Every Region_Code2 and Region_Of_Incorporation_Code2: a two-character region code, such as WANo. StateCode can hold the full region name, such as ALABAMA, so send the two-character code instead. An owner's Region_Code2 must be exactly two characters.
GetAdvancedContactCompanyType, {"CompanyType": {"request": {"CountryISO2": "US"}}}Company_Type, such as C CorporationYes. A US company sends Limited Liability Corporation, C Corporation, S Corporation, Partnership or Other.
GetNAICS, {}Industry_Classification: an Industry, such as Software PublishersNo, any text is accepted
GetAdvancedContactJobTitles, {}Job_Title of the authorized contact (Director) and of each owner (Owner)No
GetIdentificationType, {}The optional Identification_Type: an IdentificationType, such as Passport or DriversLicenseNo

The identification document belongs to the authorized contact, not the company: send the type and number of their passport, driver's license or other personal ID, even though the fields sit in BusinessEntityInformation.

#What can go wrong

Check the HTTP status and OperationStatus.Success on every response. When a call fails, Success is false and OperationStatus.Errors is a list of messages that say why. Errors covers the responses every endpoint shares.

  • The company stays below Advanced. Its Identity profile is missing something, such as its business tax ID, part of its address or a document. Check its Identity profile in the web app and finish it as in step 1: no API call uploads documents.
  • The company isn't connected to yours. Submitting or reading a client company's profile without a connection returns HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource. Connect it first: see Connect existing accounts.
  • A different company in IssuerAccountNumber returns HTTP 401 with Not authorized to access this resource. Send the SPN that your credentials belong to.
  • BeneficiaryAccountNumber isn't a company. A personal (PAT) account returns HTTP 400 with Beneficiary account number is invalid, and an account number that doesn't exist returns UserId Invalid.
  • A missing or invalid field returns HTTP 400 with its own message, such as BusinessEntityInformation : Company_Type is invalid. When Country_Of_Registration_Code2 is US, Country_Of_Incorporation_Code2 and the business's Country_Code2 must be US, and so must the authorized contact's Country_Code2 in an international profile.
  • Owners left out or rejected. With IsEligibleOwnership set to true, Owners needs at least one owner, each with a Percentage_Owned from "26" to "100", and together no more than 100%. An empty list fails with OwnerInformation - Owners is mandatory. In an international profile, a share of "25" or less fails with a message such as OwnerInformation[0] :Percentage_Owned must be between 25 and 100, and shares that add up to more than 100% fail with Total ownership percentage cannot exceed 100. With IsEligibleOwnership false or left out, Xtrm doesn't save Owners, so send true whenever you list owners.
  • Phone number format. Send Business_Phone as digits only, with no spaces, dashes, brackets or +. For a US number, send the 10 digits without the leading 1, such as 2065551234. For a number outside the US, start with the country calling code, such as 442071234567. Xtrm stores the value as you send it and uses it in this format when it sets up the company's payment services, so format the number before you submit it.
  • A misspelled root key or a GET. The root keys differ from the operation names (AdvancedProfile, AdvancedProfileStatus, AdvancedProfileDetails), and every call here is a POST. See Requests and responses.
  • Unexpected statuses. The status call returns Submitted, Pending, Approved or Deactive, and it's the one to follow. In the details call, Status is Approved, Pending, or empty or null, and it can stay empty after approval.

#Next steps

For every field, see the Advanced profile (KYB) reference.