Skip to main content

Get business by ID

GET 

/business/{businessId}

Provides all business information for a single business, referenced by the “businessId” value provided when the business was created. The response will include current status on the business vetting process.

Path Parameters​


    businessId stringrequired

    Id of a business

    Example: 60ff7262-d373-4242-8fc8-a3ecfb51d0c1

Responses​

OK

Response Body

application/json

    businessIdstringrequired

    Persistent ID assigned to this business

    Example: 11111111-1111-1111-1111-111111111111

    legalNamestringrequired

    Legal registered name of the business

    Example: Sample Business Inc.

    primaryNamestringrequired

    Primary DBA / public business name

    Example: Sample Business

    dunsNumberstring

    While DUNS number is optional in the API, the service might decline businesses without a DUNS number depending on the API key configuration. If DUNS is provided, Hiya will verify the business information against the DUNS record on file, even if DUNS is optional.

    Example: 123456789

    einVatNumberstring
    Example: GB123456789

    countrystringrequired

    Primary country of operation for business headquarters. Provide as an ISO-3166-1 alpha-2 country code, for example “US”, “GB”, “DE”.

    Example: GB

    regionstring

    State/province or similar of the business headquarters. IMPORTANT: This field is required for businesses registered in either US or CA, using the two-character territory code (BC, ON, QB or similar) or the two-character state code (WA, NY, PR or similar).

    Example: West Yorkshire

    citystringrequired
    Example: Leeds

    postcodestring
    Example: LS1

    streetAddressLine1string
    Example: 123 Any St.

    streetAddressLine2string
    Example: Suite 200

    industrystringrequired

    Primary industry of operations by this business (not limited to only industry purpose that creates phone calls)

    Format: industry (string)

    Possible values: [ACCOUNTING_OR_FINANCE, BILLING_AND_COLLECTIONS, BUSINESS_SERVICES, CHARITY_OR_FUNDRAISING, COMMUNICATIONS, CUSTOMER_SERVICE, DELIVERY_OR_SHIPPING, EDUCATION, FINANCIAL_SERVICES, GOVERNMENT_OR_PUBLIC_SERVICES, HEALTHCARE_OR_PHARMACY, INSURANCE, LEGAL_SERVICES, NOTIFICATIONS_OR_SCHEDULING, REAL_ESTATE, RETAIL, SALES, SOFTWARE_OR_TECHNOLOGY_OR_MEDIA, SURVEYS_AND_MARKET_RESEARCH, TRAVEL_OR_HOSPITALITY, OTHER]

    Example: ACCOUNTING_OR_FINANCE

    contactobject

    Name, email address, phone number, and job title of a representative at the business


    firstNamestringrequired
    Example: Sample

    lastNamestringrequired
    Example: Person

    emailstringrequired
    Example: sample@sample.com

    titlestringrequired
    Example: CEO

    phonestringrequired
    Example: +4412345678990

    numberOfEmployeesstringrequired
    Format: NumberOfEmployees (string)

    Possible values: [BETWEEN_1_AND_10, BETWEEN_11_AND_50, BETWEEN_51_AND_200, BETWEEN_201_AND_500, BETWEEN_501_AND_2000, BETWEEN_2001_AND_10000, MORE_THAN_10001]

    Example: BETWEEN_1_AND_10

    websitestringrequired

    Primary website (will be used in business verification)

    Example: www.hiya.com

    registeredstringrequired

    Time when this business record was created

    Format: string<date-time>
    Example: 2026-02-02T08:30:00Z

    updatedstringrequired

    Last time that any information changed for this business

    Format: string<date-time>
    Example: 2026-02-02T08:45:00Z

    statusstringrequired

    Current status of the registration process for the business. “pending” indicates registration is still in progress. “registered” indicates registration is complete and the business may now have registered phone numbers.

    “error_duns_mismatch” indicates that the provided business information did not align with the business information on record for the provided DUNS number; update the business information to attempt registration again.

    Possible values: [pending, registered, error_duns_mismatch]

    Example: pending

    registeredTnsintegerrequired

    Quantity of registered phone numbers for this business (does not include phone numbers that failed to register.)

    Format: integer<int32>
    Example: 10

Example from Schema​

{
"businessId": "11111111-1111-1111-1111-111111111111",
"legalName": "Sample Business Inc.",
"primaryName": "Sample Business",
"dunsNumber": "123456789",
"einVatNumber": "GB123456789",
"country": "GB",
"region": "West Yorkshire",
"city": "Leeds",
"postcode": "LS1",
"streetAddressLine1": "123 Any St.",
"streetAddressLine2": "Suite 200",
"industry": "ACCOUNTING_OR_FINANCE",
"contact": {
"firstName": "Sample",
"lastName": "Person",
"email": "sample@sample.com",
"title": "CEO",
"phone": "+4412345678990"
},
"numberOfEmployees": "BETWEEN_1_AND_10",
"website": "www.hiya.com",
"registered": "2026-02-02T08:30:00Z",
"updated": "2026-02-02T08:45:00Z",
"status": "pending",
"registeredTns": 10
}