Vision Developers
POST/api/v1/companies/commands

Core form commands for companies

The approved contract does not provide a longer purpose statement for this operation.

App
People & Companies
Contract
People & Companies API 1.5.0
Lifecycle
preview
Runtime
restricted
Operation ID
postCompaniesCommands
Canonical origin
https://directory.runonvision.com

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

Core form commands for companies

The owning App is Vision People & Companies. Directory owns these facts, its workspace authorization, and its change feed. Apps store a record's id and keep their own data; app-specific fields go in namespaced extensions.

Business use cases and out-of-scope behavior are not yet declared in the approved OpenAPI description.

Request

POST https://directory.runonvision.com/api/v1/companies/commands

Authentication and authorization

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

  • Required scope: directory:companies:write

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.
  • Content-Type: application/json — required for the documented request representation.

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

Path and query parameters

NameLocationTypeRulesDescription
Idempotency-Keyheaderstringoptional; pattern ^[A-Za-z0-9._:-]{16,160}$Makes a write safe to retry: the same key replays the first answer.
Vision-Acting-Forheaderstringoptional; maximum length 600An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.

Request body

Media type: application/json. The body is required.

FieldTypeRulesDescription
schemaVersion"vision-directory-command.v1"requiredNot described in the contract.
commandTypeperson.create | person.update | person.delete | person.restore | person.company.link | person.company.leave | person.email.add | person.email.remove | person.email.make-primary | person.phone.add | person.phone.remove | person.phone.make-primary | person.social.add | person.social.remove | person.address.add | person.address.remove | person.consent.record | company.create | company.update | company.delete | company.restore | company.email.add | company.email.remove | company.email.make-primary | company.phone.add | company.phone.remove | company.phone.make-primary | company.social.add | company.social.remove | company.address.add | company.address.remove | company.consent.recordrequiredNot described in the contract.
idempotencyKeystringrequiredNot described in the contract.

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 'https://directory.runonvision.com/api/v1/companies/commands' \
  --request POST \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "schemaVersion": "vision-directory-command.v1",
    "commandType": "person.create",
    "idempotencyKey": "<idempotencyKey>"
  }'
JavaScript (server-side)
const response = await fetch('https://directory.runonvision.com/api/v1/companies/commands', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
  "schemaVersion": "vision-directory-command.v1",
  "commandType": "person.create",
  "idempotencyKey": "<idempotencyKey>"
}),
}

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(
    'https://directory.runonvision.com/api/v1/companies/commands',
    data=json.dumps({"schemaVersion":"vision-directory-command.v1","commandType":"person.create","idempotencyKey":"<idempotencyKey>"}).encode(),
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Content-Type": "application/json"
},
    method='POST',
)
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
200OKobject
400Some details are missing or not validobject
401No credential, or not a valid oneobject
403Not allowed (also returned for an unknown workspace)object
404No such record in this workspaceobject
409Duplicate on the record, stale version, reused idempotency key, or sample_record_outbound_blocked (a sample record cannot be given permission to be contacted)object
413The request body is over 64 KiB (code payload_too_large)object
415The request body is not application/json (code unsupported_media_type)object
500An unexpected defect (code internal_error); not retryable, report the requestIdobject
503The database is temporarily unavailable (code dependency_unavailable); retry with backoffobject

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 — Some details are missing or not valid
  • 401 — No credential, or not a valid one
  • 403 — Not allowed (also returned for an unknown workspace)
  • 404 — No such record in this workspace
  • 409 — Duplicate on the record, stale version, reused idempotency key, or sample_record_outbound_blocked (a sample record cannot be given permission to be contacted)
  • 413 — The request body is over 64 KiB (code payload_too_large)
  • 415 — The request body is not application/json (code unsupported_media_type)
  • 500 — An unexpected defect (code internal_error); not retryable, report the requestId
  • 503 — The database is temporarily unavailable (code dependency_unavailable); retry with backoff

Collection behavior

Pagination: not declared. Filtering/search: not declared. 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 detailed operation description.
  • The request body has no purpose or conditional-rule description.
  • Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Contract history and evidence