{
"businessProfile": {
"id": "664a1b2c3d4e5f6071829300",
"name": "Acme Retail Profile",
"companyLegalName": "Acme Incorporated",
"taxIdLast4": "6789",
"addressCountry": "US",
"verificationStatus": "unverified",
"supportingDocumentCount": 0,
"createdAt": "2026-07-26T12:00:00Z"
}
}
{
"error": "validation_failed",
"fields": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
]
}
Business Verification (v2)
Create Business Profile
Create a business identity profile; for US profiles KYB verification starts automatically once the identity is complete.
POST
/
v2
/
business-profiles
{
"businessProfile": {
"id": "664a1b2c3d4e5f6071829300",
"name": "Acme Retail Profile",
"companyLegalName": "Acme Incorporated",
"taxIdLast4": "6789",
"addressCountry": "US",
"verificationStatus": "unverified",
"supportingDocumentCount": 0,
"createdAt": "2026-07-26T12:00:00Z"
}
}
{
"error": "validation_failed",
"fields": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
]
}
Creates a business profile on your account. Only
A complete legal identity is unique within the account. A duplicate create returns
name is required — you can create a draft and fill it in later. When the profile carries a complete identity (companyLegalName, taxId, addressCountry, businessContactFirstName, businessContactLastName) and addressCountry is US, KYB verification starts automatically. For any other country, the profile stays unverified: once it carries companyLegalName, taxId, and addressCountry, uploading a supporting document moves it to admin review instead of automated KYB.
For a US profile, submission is asynchronous, so this response still reports verificationStatus: "unverified"; it moves to pending shortly after, once the submission is accepted. Poll Get Business Profile or subscribe to the business_profile.* webhooks rather than reading the outcome off the create response.
Requires a live key. This endpoint is idempotent: send an
Idempotency-Key header to make retries safe.409 business_identity_exists and businessProfileId; fetch that existing business and confirm its current revision on the number request. The API does not silently merge profiles or start a second paid verification for the duplicate.
Body Parameters
string
required
Profile label (distinct from the brand name — an account can hold several profiles). Max 100 characters.
string
account_business for your account’s legal entity or client_business for a client you represent. Once confirmed, the relationship is immutable.string
Registered legal entity name, as it appears on IRS/registry records. For US TIN match, the sanitized name must be ≤ 40 characters.
string
EIN / TIN. Validated against
addressCountry’s format; stored in its canonical form.string
Type of value in
taxId (e.g. ein, cbn, neq, provincial_number, registration_number). Auto-defaulted for countries with exactly one legal value; CA requires an explicit choice.string
ISO 3166-1 country (alpha-2, alpha-3, or full name). Must be a supported jurisdiction.
string
Authorized contact first name (required by the carrier registry at verification).
string
Authorized contact last name.
string
Street.
string
City.
string
State/region (coerced to a 2-letter code where applicable).
string
Postal code.
string
Brand name.
string
Business website URL.
string
Business contact email.
string
Industry / vertical.
Response Fields
object
The created profile (see Get Business Profile).
verificationStatus is unverified in this response even when KYB was auto-submitted — the move to pending happens asynchronously. taxIdLast4 is returned in place of the full tax id.Examples
cURL
curl -X POST "https://api.tracklysms.com/api/v2/business-profiles" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Idempotency-Key: create-acme-profile-1" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Retail Profile",
"businessRelationship": "account_business",
"companyLegalName": "Acme Incorporated",
"taxId": "12-3456789",
"addressCountry": "US",
"businessContactFirstName": "Jane",
"businessContactLastName": "Doe"
}'
Python
import requests
resp = requests.post(
"https://api.tracklysms.com/api/v2/business-profiles",
headers={"X-Api-Key": "trk_your_api_key_here", "Idempotency-Key": "create-acme-profile-1"},
json={
"name": "Acme Retail Profile",
"companyLegalName": "Acme Incorporated",
"taxId": "12-3456789",
"addressCountry": "US",
"businessContactFirstName": "Jane",
"businessContactLastName": "Doe",
},
)
print(resp.json()["businessProfile"]["verificationStatus"])
{
"businessProfile": {
"id": "664a1b2c3d4e5f6071829300",
"name": "Acme Retail Profile",
"companyLegalName": "Acme Incorporated",
"taxIdLast4": "6789",
"addressCountry": "US",
"verificationStatus": "unverified",
"supportingDocumentCount": 0,
"createdAt": "2026-07-26T12:00:00Z"
}
}
{
"error": "validation_failed",
"fields": [
{ "field": "taxId", "code": "compliance_tax_id_format", "message": "taxId format is invalid for US", "legacy": "compliance_tax_id_format:US" }
]
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_body | Request body must be a JSON object. |
| 400 | missing_name | name is required. |
| 403 | sandbox_read_only | Sandbox keys cannot create profiles — use a live key. |
| 403 | api_key_has_no_owner | The API key is not linked to a user and cannot create profiles. |
| 403 | account_locked / daily_cap_hit | A rejected/locked profile on the account, or the daily verification cap, blocks new profiles. |
| 422 | validation_failed | One or more identity fields are invalid — see fields. For CA profiles, identifierType is required. |
Next Steps
Validate first
Dry-run field validation before creating.
Submission history
Track the KYB verdict.