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_TOKENenvironment variable. See Authentication. - Your company's account number, the
SPNthat owns your API credentials (SPN1111222in the samples). You send it asIssuerAccountNumber. If you use pseudo credentials, send theSPNof the company you act on behalf of. - The account number of the company the profile is for, sent as
BeneficiaryAccountNumber: your ownSPN, or theSPNof a client company (SPN7777555in the samples). For a client company, your company needs a connection to it, which it has with every company it creates withCreateBeneficiary. Check one withGetConnectedStatus, 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.
Use test data in the sandbox
The sandbox holds only test data and is separate from your production account. Never use real financial data in the sandbox. The profile carries personal data, such as dates of birth and tax and identification numbers, so we recommend keeping it out of your logs.
#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 andIsPublicallyTraded. 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:
| Object | What it holds | Who completes it |
|---|---|---|
BusinessEntityInformation | Legal 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 document | Every company. The industry, purpose and expected activity are required in an international profile. |
AuthorizedContactInformation | The person who represents the company: name, job title, email address, business phone, date of birth, citizenship and address | An international profile. A USA Only profile doesn't need it. |
OwnerInformation | IsPublicallyTraded (yes or no), IsEligibleOwnership and the Owners list | Every 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:
| Step | Where | What you get |
|---|---|---|
| 1 | The Xtrm web app | The company's Identity profile is complete, with its documents on file, and its level is Advanced. |
| 2 | CompanyAdvancedProfile | The submission is saved and goes to Xtrm for review. |
| 3 | CompanyAdvancedProfileStatus | The review status, until it's Approved. |
| 4 | GetCompanyAdvancedProfileDetails | The profile as Xtrm holds it. |
- 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
AccountIdentityLevelreadsAdvanced. For a client company,CheckBeneficiaryExistreturns 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. - 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,BeneficiaryAccountNumberandCountry_Of_Registration_Code2are required.Payments_Typeis required for a company registered in the US and must beUSA OnlyorInternational. For a company registered anywhere else, Xtrm sets it toInternational, whatever you send. BusinessEntityInformation: every profile needsCompany_Type,Website,Tax_Identification_Number,Country_Of_Incorporation_Code2,Region_Of_Incorporation_Code2,Address_Line_1,City,Region_Code2,Postal_CodeandCountry_Code2. An international profile also needsIndustry_Classification,Purpose_Of_Transactionsand the expected activity:Expected_Currencies,Countries_Sending_ToandCountries_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), andExpected_Annual_VolumeandExpected_Transaction_Amountas numeric strings.AuthorizedContactInformation: an international profile needs every field:First_Name,Last_Name,Job_Title,Email_Address,Business_Phone(digits only, such as2065551234),Date_Of_Birth(mm/dd/yyyy),Citizenship, and the address inAddress_Line_1,City,Region_Code2,Postal_CodeandCountry_Code2. A USA Only profile doesn't need the authorized contact.OwnerInformation:IsPublicallyTraded(yesorno) is required. For a publicly traded company (yes), sendTicker_Symbol, which an international profile requires; Xtrm doesn't keepOwnersfor a publicly traded company. For a company that isn't publicly traded (no), setIsEligibleOwnershiptotrue, a JSON boolean, when one or more people own 26% or more of the company, and list those owners inOwners. Each owns 26% or more and together they can't own more than 100%, so a profile lists one to three owners. Xtrm readsOwnersonly whenIsEligibleOwnershipistrue, so withfalse, or without the field, the list isn't saved.- Each owner:
Percentage_Ownedis 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 needsFirst_Name,Last_Name,Job_Title,Date_of_Birth(mm/dd/yyyy),Citizenship, and the address inAddress_Line_1,City,Region_Code2,Postal_CodeandCountry_Code2.Middle_NameandEmail_Addressare 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" } ] } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }, ], }, }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "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", }, ], }, }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "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" } ] } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "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" } ] } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfile'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ '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', ], ], ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Copy the field names exactly
The date-of-birth field is
Date_Of_BirthinAuthorizedContactInformationbutDate_of_Birthin each owner, andIsPublicallyTradedis spelled as shown. The body's root key isAdvancedProfile, not the operation name.Response{ "AdvancedProfileResponse": { "AdvancedProfileResult": { "BeneficiaryID": "SPN7777555", "Message": "Advanced Profile Submitted Successfully", "OperationStatus": { "Success": true, "Errors": null } } } }Check
OperationStatus.Success. On success,Messageconfirms the submission withAdvanced Profile Submitted Successfully. If the profile is missing something, the call fails instead, andOperationStatus.Errorslists 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, theSPNof the company whose profile was submitted. - Root of
- Poll the application status
CompanyAdvancedProfileStatusreturns the status of the application inMessage: one ofSubmitted,Pending,ApprovedorDeactive. Send yourIssuerAccountNumberand the company'sSPNasBeneficiaryAccountNumber.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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ AdvancedProfileStatus: { request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN7777555', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "AdvancedProfileStatus": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "AdvancedProfileStatus": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "AdvancedProfileStatus": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Register/CompanyAdvancedProfileStatus'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'AdvancedProfileStatus' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN7777555', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "AdvancedProfileStatusResponse": { "AdvancedProfileStatusResult": { "BeneficiaryID": "SPN7777555", "Message": "Approved", "OperationStatus": { "Success": true, "Errors": null } } } }SubmittedandPendingmean 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, untilMessageisApproved. If you getDeactive, stop polling and contact [email protected].If the company has no profile on file, the call fails with HTTP
400andPlease complete company advanced profile to view the status.Keep:
Message, the current status. - Read back the submitted profile
GetCompanyAdvancedProfileDetailsreturns 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ AdvancedProfileDetails: { request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN7777555', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "AdvancedProfileDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "AdvancedProfileDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "AdvancedProfileDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN7777555" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Register/GetCompanyAdvancedProfileDetails'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'AdvancedProfileDetails' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN7777555', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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 isExpected_Transaction_Amount. IsPublicallyTradedcan come back capitalized, such as"No". Xtrm acceptsyesandnoin 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_Otherholds the authorized contact's job title whenJob_TitleisOther; 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
Statuscan be empty ornulleven 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.
- The expected amount per transaction comes back as
#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 body | Fields it fills | Checked |
|---|---|---|
GetAdvancedContactCountry, {} | Country_Of_Registration_Code2, Country_Of_Incorporation_Code2, every Country_Code2 and Citizenship: the two-character CountryCode, such as US | Yes, 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 WA | No. 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 Corporation | Yes. A US company sends Limited Liability Corporation, C Corporation, S Corporation, Partnership or Other. |
GetNAICS, {} | Industry_Classification: an Industry, such as Software Publishers | No, 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 DriversLicense | No |
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
400withNot 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
IssuerAccountNumberreturns HTTP401withNot authorized to access this resource.Send theSPNthat your credentials belong to. BeneficiaryAccountNumberisn't a company. A personal (PAT) account returns HTTP400withBeneficiary account number is invalid, and an account number that doesn't exist returnsUserId Invalid.- A missing or invalid field returns HTTP
400with its own message, such asBusinessEntityInformation : Company_Type is invalid.WhenCountry_Of_Registration_Code2isUS,Country_Of_Incorporation_Code2and the business'sCountry_Code2must beUS, and so must the authorized contact'sCountry_Code2in an international profile. - Owners left out or rejected. With
IsEligibleOwnershipset totrue,Ownersneeds at least one owner, each with aPercentage_Ownedfrom"26"to"100", and together no more than 100%. An empty list fails withOwnerInformation - Owners is mandatory. In an international profile, a share of"25"or less fails with a message such asOwnerInformation[0] :Percentage_Owned must be between 25 and 100, and shares that add up to more than 100% fail withTotal ownership percentage cannot exceed 100. WithIsEligibleOwnershipfalseor left out, Xtrm doesn't saveOwners, so sendtruewhenever you list owners. - Phone number format. Send
Business_Phoneas digits only, with no spaces, dashes, brackets or+. For a US number, send the 10 digits without the leading 1, such as2065551234. For a number outside the US, start with the country calling code, such as442071234567. 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 aPOST. See Requests and responses. - Unexpected statuses. The status call returns
Submitted,Pending,ApprovedorDeactive, and it's the one to follow. In the details call,StatusisApproved,Pending, or empty ornull, and it can stay empty after approval.
#Next steps
Take a client company from first contact to its first batch payment as a managing platform.
Fund your walletFund a company wallet by bank transfer, bank debit or credit card once funding is unlocked.
Connections and manager servicesWhat a connection lets your company do for another account, and how manager services add to it.
Create a batch paymentPay many recipients in one request and track every item's status.
For every field, see the Advanced profile (KYB) reference.