Response structure

Every search returns a single JSON object. All top-level fields are always present — disabled features return null rather than being omitted. The one exception is matchSelection, which is omitted entirely unless match selection ran for the search.

Top-level shape

{
  "meta": { ... },
  "businesses": [ ... ],
  "regulatory": { ... },
  "sanctions": null,       // null when sanctionsScreening is false
  "website": null,         // null when websiteAnalysis is false
  "errors": null,          // null when all sources succeeded
  "matchSelection": { ... } // omitted when match selection is off
}

`meta`

Metadata about the search itself. Your original query is nested under submitted.

{
  "meta": {
    "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "searchedBy": "user@example.com",
    "searchedAt": "2024-01-15T10:30:00Z",
    "submitted": {
      "name": "Shopify Inc",
      "website": "https://shopify.com",
      "params": {
        "businessRegistry": true,
        "regulatoryRegistry": true,
        "sanctionsScreening": false,
        "sanctionsThreshold": 0.85,
        "websiteAnalysis": false
      }
    },
    "status": "completed",
    "duration": 24318
  }
}

Field	Description
`searchId`	UUID — use with `GET /search/{id}` to retrieve this result later
`searchedBy`	Email of the user who ran the search (may be null for API keys)
`searchedAt`	ISO 8601 timestamp of when the search was executed
`submitted.name`	The company name you submitted
`submitted.website`	Website URL if provided (null otherwise)
`submitted.params`	The parameters that were used, with your account defaults applied. Thresholds are on the same 0–1 scale as the request (and as every `score`/`matchScore` in the response).
`status`	`completed`, `completed-with-errors`, `error`, or `loading` (a still-running result fetched via `GET /search/{id}`)
`duration`	Total time in milliseconds

completed-with-errors means at least one data source succeeded. Check the errors object to see which sources failed.

`businesses`

An array of business registry matches, sorted by match confidence.

{
  "businesses": [
    {
      "legalName": {
        "name": "Shopify Inc.",
        "matchScore": 0.98
      },
      "matchId": "8f14e45f-ceea-467a-9f8e-2bd1f3a1c7d2",
      "match": {
        "score": 0.98,
        "baseline": "query",
        "fields": [
          { "field": "name", "label": "Name", "score": 0.98, "status": "matched" }
        ]
      },
      "entityType": "Corporation",
      "jurisdiction": "FED",
      "jurisdictionLabel": "Federal",
      "status": "Active",
      "incorporationDate": "2011-09-14",
      "registrationNumbers": [
        { "label": "Federal Corporation Number", "value": "796223-2" },
        { "label": "Business Number (CRA)", "value": "837620872" }
      ],
      "addresses": [
        {
          "street": "151 O'Connor Street",
          "unit": null,
          "city": "Ottawa",
          "province": "Ontario",
          "postalCode": "K2P 2L8",
          "country": "Canada",
          "raw": null
        }
      ],
      "alternateNames": ["Shopify", "Shopify Commerce"],
      "people": [
        {
          "name": "Tobias Lutke",
          "roles": ["Director"],
          "roleDetails": [{ "category": "director", "label": "Director" }],
          "addresses": []
        }
      ],
      "sourceUrl": "https://ised-isde.canada.ca/cc/lgcy/fdrlCrpDtls.html?corpId=7962232",
      "businessReport": null
    }
  ]
}

Field	Description
`legalName.matchScore`	Name-only confidence that this result matches your query (0–1)
`matchId`	Stable id for this result within the search. Pass it to `POST /search/{id}/selection` to resolve the search to this entity. `null` on searches run before match selection existed.
`match`	Aggregate identity match (0–1 `score`, `baseline`, per-field `fields`). Scored against your linked business record when the search was created with a `businessId`, otherwise against the query name. Richer than `legalName.matchScore`.
`jurisdiction`	Canonical jurisdiction code — `FED`, `ON`, `BC`, etc. Round-trippable: pass it straight back to `/verify`, `/business-reports`, or `/businesses`.
`jurisdictionLabel`	The same jurisdiction spelled out for display — `Federal`, `Ontario`. Absent on searches run before this field was added.
`status`	`Active`, `Dissolved`, `Cancelled`, etc.
`registrationNumbers`	All registration IDs with human-readable labels
`alternateNames`	Operating names, DBA names, and aliases
`people`	Directors, officers, and others on the registry record — each with `roles` and `roleDetails`
`sourceUrl`	Link to the official public registry record, or `null` when the source has no public page
`businessReport`	Embedded report data once one has been fetched for this business, else `null`

`regulatory`

Flat arrays of regulatory registry matches. Empty arrays when no matches are found.

{
  "regulatory": {
    "craCharities": [],
    "fintracMsb": [],
    "agcoCannabis": [],
    "healthCanadaCannabis": [],
    "mohServiceProviders": [],
    "bankOfCanadaRps": [],
    "wsibClassifications": [],
    "onBusinessLicences": [],
    "torontoBusinessLicences": [],
    "vancouverBusinessLicences": [],
    "rbqLicences": [],
    "aglcGamingRegistrants": [],
    "aglcCannabis": [],
    "bcCannabisRetail": [],
    "montrealCommercialEstablishments": [],
    "calgaryBusinessLicences": [],
    "edmontonBusinessLicences": [],
    "gleif": []
  }
}

Key	Registry	Regulator
`craCharities`	Registered charities	Canada Revenue Agency
`fintracMsb`	Money Services Businesses	FINTRAC
`agcoCannabis`	Cannabis retail licences	AGCO (Ontario)
`healthCanadaCannabis`	Cannabis production licences	Health Canada
`mohServiceProviders`	Health service providers	Ontario Ministry of Health
`bankOfCanadaRps`	Retail Payments Supervision (RPS)	Bank of Canada
`wsibClassifications`	Business classifications	WSIB (Ontario)
`onBusinessLicences`	Business licences & registrations	Ontario
`torontoBusinessLicences`	Business licences & permits	City of Toronto
`vancouverBusinessLicences`	Business licences	City of Vancouver
`rbqLicences`	Building contractor licences	Régie du bâtiment (Québec)
`aglcGamingRegistrants`	Gaming registrants	AGLC (Alberta)
`aglcCannabis`	Cannabis licensees	AGLC (Alberta)
`bcCannabisRetail`	Cannabis retail stores	British Columbia
`montrealCommercialEstablishments`	Commercial establishments	City of Montréal
`calgaryBusinessLicences`	Business licences	City of Calgary
`edmontonBusinessLicences`	Business licences	City of Edmonton
`gleif`	Legal Entity Identifiers (Canada)	GLEIF

Each item includes legalName ({name, matchScore}), match (the aggregate identity score, same shape as businesses[].match), alternateNames, registrationNumber, status, addresses, and a details object of registry-specific fields. See Regulatory registry for per-registry examples.

`sanctions`

Always present in the response. null when sanctionsScreening is false. When enabled, an object with query, totalMatches, and matches. See Sanctions screening for full documentation.

This describes the sanctions field within a search response. For the standalone POST /sanctions endpoint, which has its own meta, results, and errors structure, see Standalone screening.

{
  "sanctions": {
    "query": "Shopify Inc",
    "totalMatches": 1,
    "matches": [
      {
        "legalName": {
          "name": "SHOPIFY INC",
          "matchScore": 0.91,
          "matchedName": "SHOPIFY INC",
          "nameScores": [{ "name": "SHOPIFY INC", "score": 0.91 }]
        },
        "alternateNames": [],
        "addresses": [],
        "details": {
          "source": "us-sanctions-ofac-sdn",
          "datasets": ["us-sanctions-ofac-sdn"],
          "countries": ["US"],
          "programs": [],
          "identifiers": [],
          "listingDate": null,
          "dateOfBirth": null,
          "remarks": null
        },
        "sourceUrls": []
      }
    ]
  }
}

`website`

Always present in the response. null when websiteAnalysis is false and no website URL was provided.

{
  "website": {
    "status": "success",
    "url": "https://shopify.com",
    "extracted": {
      "legalName": "Shopify Inc.",
      "descriptions": ["Shopify is a commerce platform..."],
      "addresses": [],
      "people": [{ "name": "Tobias Lütke", "roles": ["CEO"] }],
      "contactInfo": { "emails": [], "phoneNumbers": [] },
      "registrations": []
    },
    "industry": {
      "naicsCode": "454110",
      "naicsCodeName": "Electronic Shopping and Mail-Order Houses"
    },
    "domain": {
      "url": "https://shopify.com",
      "createdAt": "1996-04-28T00:00:00Z"
    }
  }
}

Field	Description
`status`	`success`, `skipped`, `not_found`, `empty`, or `error`
`extracted.legalName`	Legal name found on the website
`extracted.people`	Named individuals with `roles`
`extracted.contactInfo`	Emails and phone numbers (E.164)
`industry.naicsCode`	6-digit NAICS classification code
`industry.naicsCodeName`	Human-readable industry description
`domain.createdAt`	Domain registration date

See Website analysis for full field documentation.

`errors`

Always present in the response. null when all sources succeeded. The search can still succeed (completed-with-errors) even if some sources fail.

{
  "errors": {
    "businessRegistry": {
      "code": "TIMEOUT",
      "message": "Business registry request timed out",
      "retryable": true
    },
    "regulatoryRegistry": null,
    "sanctionsScreening": null,
    "websiteAnalysis": null,
    "general": null
  }
}

errors is null when every source succeeded. Otherwise all five keys are present and the sources that succeeded are null — so branch on each key’s value, not on whether the key exists. general carries a search-wide failure not tied to one source (a timeout, or an unexpected error); when it is set, meta.status is error. See Error handling for the full list of error codes.

`matchSelection`

Which entry in businesses the search resolved to. Present only when match selection ran — set matchSelection: true on the request, or enable it in your account’s search settings. Omitted entirely otherwise.

{
  "matchSelection": {
    "status": "needs_review",
    "selectedMatchId": null,
    "statusUrl": "/api/v1/search/550e8400-e29b-41d4-a716-446655440000",
    "selectionUrl": "/api/v1/search/550e8400-e29b-41d4-a716-446655440000/selection"
  }
}

Field	Description
`status`	`auto_selected` (the rule picked a result), `selected` (a person or an API call picked it), `needs_review` (nothing picked yet), `no_match_found` (no result matched — below the no-match floor, or none returned), or `no_selection` (reviewed, deliberately not proceeding)
`selectedMatchId`	The chosen result’s `businesses[].matchId`. `null` for `needs_review`, `no_match_found`, and `no_selection`
`statusUrl`	Poll this to observe the search once a match is picked in Current. Returned while `needs_review`, `no_match_found`, or `no_selection`
`selectionUrl`	POST here to resolve the search yourself. Returned while `needs_review`, `no_match_found`, or `no_selection`

statusUrl and selectionUrl are paths, not absolute URLs. Resolve them against the API host — https://api.getcurrent.ca accepts them as-is.

A search lands in needs_review when a plausible result exists but none clears your account’s auto-select confidence, when the top result’s registry status isn’t one you allow, or when the top two results tie — Current won’t guess between equals. It lands in no_match_found when no result clears the no-match floor (or the search returned nothing).

Resolving a search

Pick the right entry from businesses and POST its matchId:

curl -X POST https://api.getcurrent.ca/v1/search/550e8400-e29b-41d4-a716-446655440000/selection \
  -H "Authorization: Bearer $CURRENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"matchId": "8f14e45f-ceea-467a-9f8e-2bd1f3a1c7d2"}'

{
  "matchSelection": {
    "status": "selected",
    "selectedMatchId": "8f14e45f-ceea-467a-9f8e-2bd1f3a1c7d2"
  }
}

The search’s comparison and discrepancy counts are recomputed against the result you chose. A matchId that isn’t part of this search returns 400 MATCH_NOT_FOUND. Or mark the search as not proceeding — when none of the results is the entity, or the only hit is one you won’t use (say, an inactive entity you’ll go back to the customer about). POST a status instead of a matchId:

curl -X POST https://api.getcurrent.ca/v1/search/550e8400-e29b-41d4-a716-446655440000/selection \
  -H "Authorization: Bearer $CURRENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "no_selection"}'

{
  "matchSelection": {
    "status": "no_selection",
    "selectedMatchId": null
  }
}

Both outcomes are reversible: POST a matchId later (for example after the customer sends updated information and you re-run the search) to pick a result.

Overview

Guides

Concepts

API Reference

Changelog

Releases

Top-level shape

`meta`

`businesses`

`regulatory`

`sanctions`

`website`

`errors`

`matchSelection`

Resolving a search

​Top-level shape

​meta

​businesses

​regulatory

​sanctions

​website

​errors

​matchSelection

​Resolving a search

Top-level shape

`meta`

`businesses`

`regulatory`

`sanctions`

`website`

`errors`

`matchSelection`

Resolving a search