Vision Developers
GET/api/crm/v1/directory-matches

Possible matches: CRM records that may be the same as another record, for a person to look at

Requires crm:settings:manage (owners and administrators). A CRM company or person beside a People & Companies record or another CRM record, with why they matched. Nothing is linked until a person says so.

App
CRM
Contract
CRM API 9.12.1
Lifecycle
preview
Runtime
restricted
Operation ID
listDirectoryMatches
Canonical origin
Not declared; gateway routing required

Availability: This is a preview contract with runtime status restricted. Publication documents an approved interface; it does not imply public production access.

Purpose and use cases

Possible matches: CRM records that may be the same as another record, for a person to look at

The owning App is Vision CRM. CRM owns its records, workflow rules, workspace membership, provenance, and record-level authorization.

Request

GET /api/crm/v1/directory-matches

This contract intentionally declares no direct server URL. Obtain the routed App origin before attempting the request.

Authentication and authorization

Send a Vision-issued bearer token for the exact App audience. The token must include the crm entitlement and satisfy the crm workspace required binding.

  • Required scope: crm:settings:manage

Human roles are not declared in OpenAPI. Record-level and business permission checks remain the owning App's authority.

Headers

  • Authorization: Bearer <access-token> — required.
  • Accept: application/json — recommended where a JSON response is declared.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

NameLocationTypeRulesDescription
statequeryopen | decidedoptionalNot described in the contract.
limitqueryintegeroptional; minimum 1; maximum 50Not described in the contract.
cursorquerystringoptionalNot described in the contract.

Request body

This operation declares no request body.

Runnable examples

Placeholder values are generated from the approved schema and are not live credentials or customer data. Replace every angle-bracket or shell variable value. Examples cannot be run until the App has a routed base URL and your client has the required grant.

cURL
curl '${APP_BASE_URL}/api/crm/v1/directory-matches' \
  --request GET \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json'
JavaScript (server-side)
const response = await fetch('${APP_BASE_URL}/api/crm/v1/directory-matches', {
  method: 'GET',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
  },
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()
Python 3 standard library
import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    '${APP_BASE_URL}/api/crm/v1/directory-matches',
    data=None,
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>"
},
    method='GET',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

StatusMeaningSchema
200One page of possible matches, with countsobject
400The request is invalidobject
401Authentication is missing or invalidobject
403The authenticated actor lacks the CRM capability or workspace bindingobject
503The CRM dependency or authenticated API configuration is unavailableobject

Success response schema

object
200 illustrative response
{}

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

  • 400 — The request is invalid
  • 401 — Authentication is missing or invalid
  • 403 — The authenticated actor lacks the CRM capability or workspace binding
  • 503 — The CRM dependency or authenticated API configuration is unavailable

Collection behavior

Pagination: declared through the parameters above. Filtering/search: declared through the parameters above. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

  • Rate limit: No operation-specific limit or 429 response is declared.
  • Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
  • Idempotency: No idempotency header or replay window is declared.
  • Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

  • Keep client credentials and bearer tokens on trusted servers.
  • Send only to the exact approved HTTPS origin and audience.
  • Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
  • Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

  • No direct server URL; gateway routing is unresolved here.
  • One or more parameters have no field-level description.
  • Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Contract history and evidence