{ "openapi": "3.1.0", "info": { "title": "Vision People & Companies (Directory) API", "version": "1.5.0", "description": "The universal facts about people and companies, shared by every Vision app. Apps store a record's `id` and keep their own data; app-specific fields go in namespaced extensions. Every call is scoped to the caller's workspace. Writes append to the change feed (`GET /api/v1/changes?since=`). The `/api/v1/views/*`, `/api/v1/presentation` and `*/commands` paths serve Vision Core's screens." }, "servers": [ { "url": "https://directory.runonvision.com", "description": "Live (once installed)" } ], "tags": [ { "name": "People" }, { "name": "Companies" }, { "name": "Affiliations" }, { "name": "Extensions" }, { "name": "Changes" }, { "name": "Core screens" }, { "name": "Health" } ], "paths": { "/health/live": { "get": { "operationId": "getHealthLive", "summary": "Process is up", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "alive" } } } }, "/health/ready": { "get": { "operationId": "getHealthReady", "summary": "Database reachable and this build's newest migration applied", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "ready" }, "503": { "description": "not ready" } } } }, "/apps/directory/v1/people/contract": { "get": { "operationId": "getAppsDirectoryV1PeopleContract", "summary": "What this App says about someone leaving", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "People contract" } } } }, "/api/v1/meta": { "get": { "operationId": "getMeta", "summary": "Service description", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "meta" } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenapiJson", "summary": "This document", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "OpenAPI" } } } }, "/api/v1/people": { "get": { "operationId": "getPeople", "summary": "List or search people", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Matches name, email, or phone digits." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "postPeople", "summary": "Create a person", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "givenName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "familyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4000 }, { "type": "null" } ] }, "preferredChannel": { "anyOf": [ { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, { "type": "null" } ] }, "preferredLanguage": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$" }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "emails": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "work", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 320 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } }, "phones": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "mobile", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 60 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } }, "socialLinks": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "linkedin", "x", "facebook", "instagram", "github", "youtube", "tiktok", "website", "other" ] }, "url": { "type": "string", "minLength": 4, "maxLength": 500 } }, "required": [ "network", "url" ], "additionalProperties": false } }, "addresses": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "main", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "isPrimary": { "default": false, "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/fetch": { "post": { "operationId": "postPeopleFetch", "summary": "Get up to 100 people by id, in one call; ids with no record come back in missing", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeDeleted": { "default": false, "type": "boolean" } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "missing" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "missing": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}": { "get": { "operationId": "getPeopleById", "summary": "Get a person by id", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Resolve a deleted record (deletedAt is set)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "patchPeopleById", "summary": "Change a person (absent fields are left alone)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "givenName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "familyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4000 }, { "type": "null" } ] }, "preferredChannel": { "anyOf": [ { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, { "type": "null" } ] }, "preferredLanguage": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$" }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "expectedVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deletePeopleById", "summary": "Delete a person (soft: restorable)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/restore": { "post": { "operationId": "postPeopleByIdRestore", "summary": "Restore a deleted person", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/consents": { "post": { "operationId": "postPeopleByIdConsents", "summary": "Record a contact permission (appends to the history)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, "purpose": { "default": "marketing", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,39}$" }, "status": { "type": "string", "enum": [ "granted", "withdrawn" ] }, "source": { "type": "string", "minLength": 1, "maxLength": 200 }, "evidence": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "channel", "status", "source" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "consents": { "type": "array", "items": { "$ref": "#/components/schemas/Consent" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/extensions/{appId}/{key}": { "put": { "operationId": "putPeopleByIdExtensionsByAppIdByKey", "summary": "Set an app's own extension field", "tags": [ "Extensions" ], "security": [ { "visionCredential": [ "directory:extensions:{appId}:write" ] } ], "x-required-scope": "directory:extensions:{appId}:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,39}$" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,62}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": {} }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "key": { "type": "string" }, "value": {} } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deletePeopleByIdExtensionsByAppIdByKey", "summary": "Remove an app's own extension field", "tags": [ "Extensions" ], "security": [ { "visionCredential": [ "directory:extensions:{appId}:write" ] } ], "x-required-scope": "directory:extensions:{appId}:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "key": { "type": "string" }, "removed": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/emails": { "post": { "operationId": "postPeopleByIdEmails", "summary": "Add emails", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "work", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 320 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/emails/{factId}": { "delete": { "operationId": "deletePeopleByIdEmailsByFactId", "summary": "Remove one of the emails", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/emails/{factId}/primary": { "post": { "operationId": "postPeopleByIdEmailsByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/phones": { "post": { "operationId": "postPeopleByIdPhones", "summary": "Add phones", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "mobile", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 60 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/phones/{factId}": { "delete": { "operationId": "deletePeopleByIdPhonesByFactId", "summary": "Remove one of the phones", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/phones/{factId}/primary": { "post": { "operationId": "postPeopleByIdPhonesByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/social-links": { "post": { "operationId": "postPeopleByIdSocialLinks", "summary": "Add social links", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "network": { "type": "string", "enum": [ "linkedin", "x", "facebook", "instagram", "github", "youtube", "tiktok", "website", "other" ] }, "url": { "type": "string", "minLength": 4, "maxLength": 500 } }, "required": [ "network", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/social-links/{factId}": { "delete": { "operationId": "deletePeopleByIdSocialLinksByFactId", "summary": "Remove one of the social links", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/addresses": { "post": { "operationId": "postPeopleByIdAddresses", "summary": "Add addresses", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "main", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "isPrimary": { "default": false, "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/addresses/{factId}": { "delete": { "operationId": "deletePeopleByIdAddressesByFactId", "summary": "Remove one of the addresses", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "patchPeopleByIdAddressesByFactId", "summary": "Change an address in place (absent fields are left alone, null clears one)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/addresses/{factId}/primary": { "post": { "operationId": "postPeopleByIdAddressesByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "People" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Person" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies": { "get": { "operationId": "getCompanies", "summary": "List or search companies", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Matches name, email, or phone digits." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "postCompanies", "summary": "Create a company", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "legalName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string", "minLength": 4, "maxLength": 500 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4000 }, { "type": "null" } ] }, "preferredChannel": { "anyOf": [ { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, { "type": "null" } ] }, "preferredLanguage": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$" }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "emails": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "work", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 320 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } }, "phones": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "mobile", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 60 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } }, "socialLinks": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "linkedin", "x", "facebook", "instagram", "github", "youtube", "tiktok", "website", "other" ] }, "url": { "type": "string", "minLength": 4, "maxLength": 500 } }, "required": [ "network", "url" ], "additionalProperties": false } }, "addresses": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "label": { "default": "main", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "isPrimary": { "default": false, "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/fetch": { "post": { "operationId": "postCompaniesFetch", "summary": "Get up to 100 companies by id, in one call; ids with no record come back in missing", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeDeleted": { "default": false, "type": "boolean" } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "missing" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "missing": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}": { "get": { "operationId": "getCompaniesById", "summary": "Get a company by id", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Resolve a deleted record (deletedAt is set)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "patchCompaniesById", "summary": "Change a company (absent fields are left alone)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "legalName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string", "minLength": 4, "maxLength": 500 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4000 }, { "type": "null" } ] }, "preferredChannel": { "anyOf": [ { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, { "type": "null" } ] }, "preferredLanguage": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$" }, { "type": "null" } ] }, "doNotContact": { "type": "boolean" }, "expectedVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteCompaniesById", "summary": "Delete a company (soft: restorable)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/restore": { "post": { "operationId": "postCompaniesByIdRestore", "summary": "Restore a deleted company", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/consents": { "post": { "operationId": "postCompaniesByIdConsents", "summary": "Record a contact permission (appends to the history)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "phone", "sms", "post" ] }, "purpose": { "default": "marketing", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,39}$" }, "status": { "type": "string", "enum": [ "granted", "withdrawn" ] }, "source": { "type": "string", "minLength": 1, "maxLength": 200 }, "evidence": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "channel", "status", "source" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "consents": { "type": "array", "items": { "$ref": "#/components/schemas/Consent" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/extensions/{appId}/{key}": { "put": { "operationId": "putCompaniesByIdExtensionsByAppIdByKey", "summary": "Set an app's own extension field", "tags": [ "Extensions" ], "security": [ { "visionCredential": [ "directory:extensions:{appId}:write" ] } ], "x-required-scope": "directory:extensions:{appId}:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,39}$" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,62}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": {} }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "key": { "type": "string" }, "value": {} } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteCompaniesByIdExtensionsByAppIdByKey", "summary": "Remove an app's own extension field", "tags": [ "Extensions" ], "security": [ { "visionCredential": [ "directory:extensions:{appId}:write" ] } ], "x-required-scope": "directory:extensions:{appId}:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "key": { "type": "string" }, "removed": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/emails": { "post": { "operationId": "postCompaniesByIdEmails", "summary": "Add emails", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "work", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 320 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/emails/{factId}": { "delete": { "operationId": "deleteCompaniesByIdEmailsByFactId", "summary": "Remove one of the emails", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/emails/{factId}/primary": { "post": { "operationId": "postCompaniesByIdEmailsByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/phones": { "post": { "operationId": "postCompaniesByIdPhones", "summary": "Add phones", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "mobile", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "value": { "type": "string", "minLength": 3, "maxLength": 60 }, "isPrimary": { "default": false, "type": "boolean" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/phones/{factId}": { "delete": { "operationId": "deleteCompaniesByIdPhonesByFactId", "summary": "Remove one of the phones", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/phones/{factId}/primary": { "post": { "operationId": "postCompaniesByIdPhonesByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/social-links": { "post": { "operationId": "postCompaniesByIdSocialLinks", "summary": "Add social links", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "network": { "type": "string", "enum": [ "linkedin", "x", "facebook", "instagram", "github", "youtube", "tiktok", "website", "other" ] }, "url": { "type": "string", "minLength": 4, "maxLength": 500 } }, "required": [ "network", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/social-links/{factId}": { "delete": { "operationId": "deleteCompaniesByIdSocialLinksByFactId", "summary": "Remove one of the social links", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/addresses": { "post": { "operationId": "postCompaniesByIdAddresses", "summary": "Add addresses", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "default": "main", "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "isPrimary": { "default": false, "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/addresses/{factId}": { "delete": { "operationId": "deleteCompaniesByIdAddressesByFactId", "summary": "Remove one of the addresses", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "patchCompaniesByIdAddressesByFactId", "summary": "Change an address in place (absent fields are left alone, null clears one)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "pattern": "^[a-z][a-z0-9 _-]{0,29}$" }, "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/{id}/addresses/{factId}/primary": { "post": { "operationId": "postCompaniesByIdAddressesByFactIdPrimary", "summary": "Make it the main one (only one per record)", "tags": [ "Companies" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "factId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "record", "duplicateHints" ], "properties": { "record": { "$ref": "#/components/schemas/Company" }, "duplicateHints": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/{id}/affiliations": { "post": { "operationId": "postPeopleByIdAffiliations", "summary": "Link a person to a company (role, start and end dates)", "tags": [ "Affiliations" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "startedOn": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "endedOn": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "companyId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "affiliation": { "$ref": "#/components/schemas/Affiliation" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/affiliations/{id}": { "patch": { "operationId": "patchAffiliationsById", "summary": "Change a role or its dates (set endedOn to end it and keep the history)", "tags": [ "Affiliations" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "startedOn": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "endedOn": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "affiliation": { "$ref": "#/components/schemas/Affiliation" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteAffiliationsById", "summary": "Remove a link made by mistake (no history kept)", "tags": [ "Affiliations" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/changes": { "get": { "operationId": "getChanges", "summary": "Changes since a sequence number, oldest first; each caller sees only the record types it may read", "tags": [ "Changes" ], "description": "Accepts a credential with any one of: directory:people:read, directory:companies:read.", "security": [ { "visionCredential": [ "directory:people:read" ] }, { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": [ "directory:people:read", "directory:companies:read" ], "parameters": [ { "name": "since", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "vision-directory-changes.v1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeEvent" } }, "nextSince": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/duplicates": { "get": { "operationId": "getDuplicates", "summary": "Records that already use an email or phone, or companies with the same name or website domain (for Import previews); names only record types the caller may read. Likely matches: nothing is merged", "tags": [ "Changes" ], "description": "Accepts a credential with any one of: directory:people:read, directory:companies:read.", "security": [ { "visionCredential": [ "directory:people:read" ] }, { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": [ "directory:people:read", "directory:companies:read" ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "name": "companyName", "in": "query", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateHint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/presentation": { "get": { "operationId": "getPresentation", "summary": "Screens for Vision Core (filtered to the caller)", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Vision Core's module presentation descriptor (navigation, views and actions), filtered to the caller. Its full shape is Core's module presentation schema; only the optional keys added in Core's design rounds are described here.", "properties": { "views": { "type": "array", "items": { "type": "object", "properties": { "primaryAction": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 60 }, { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "minLength": 1, "maxLength": 60 } } ], "description": "A record's one main action, or an ordered list of them where the first that applies to the record wins. Each id is one of the view's own actions. Absent: no main action." } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "inputType": { "type": "string", "enum": [ "text", "email", "tel", "url", "date", "datetime-local" ], "description": "The browser input to use for the form field. \"url\" asks for a web address, such as a company website." }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "email", "tel", "url", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "postal-code", "country", "country-name", "bday", "language" ], "description": "The browser autofill hint for the form field (for example \"given-name\", \"organization\" or \"postal-code\"), so the browser can offer what it already knows. \"off\" turns autofill off." } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/views/people": { "get": { "operationId": "getViewsPeople", "summary": "People list screen", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Matches name, email, or phone digits." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/views/people/{reference}": { "get": { "operationId": "getViewsPeopleByReference", "summary": "Person screen", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:people:read" ] } ], "x-required-scope": "directory:people:read", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Person" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/views/companies": { "get": { "operationId": "getViewsCompanies", "summary": "Companies list screen", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Matches name, email, or phone digits." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyPage" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/views/companies/{reference}": { "get": { "operationId": "getViewsCompaniesByReference", "summary": "Company screen", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Company" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/views/company-options": { "get": { "operationId": "getViewsCompanyOptions", "summary": "Company picker", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:companies:read" ] } ], "x-required-scope": "directory:companies:read", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/people/commands": { "post": { "operationId": "postPeopleCommands", "summary": "Core form commands for people", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:people:write" ] } ], "x-required-scope": "directory:people:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandEnvelope" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/companies/commands": { "post": { "operationId": "postCompaniesCommands", "summary": "Core form commands for companies", "tags": [ "Core screens" ], "security": [ { "visionCredential": [ "directory:companies:write" ] } ], "x-required-scope": "directory:companies:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes a write safe to retry: the same key replays the first answer.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,160}$" } }, { "name": "Vision-Acting-For", "in": "header", "required": false, "description": "An App only: the percent-encoded name of the person it is acting for, stored with the change. A name, never a contact value.", "schema": { "type": "string", "maxLength": 600 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandEnvelope" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "visionCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A Vision Core credential (vision-service-credential.v1, at most five minutes) with audience vision-directory[-tier], entitlement `directory` and a DWS- workspace reference. Scopes: directory:people:read|write, directory:companies:read|write, directory:extensions::write." } }, "responses": { "InvalidRequest": { "description": "Some details are missing or not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthenticated": { "description": "No credential, or not a valid one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Not allowed (also returned for an unknown workspace)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such record in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Duplicate on the record, stale version, reused idempotency key, or sample_record_outbound_blocked (a sample record cannot be given permission to be contacted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "The request body is over 64 KiB (code payload_too_large)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "The request body is not application/json (code unsupported_media_type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "An unexpected defect (code internal_error); not retryable, report the requestId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "The database is temporarily unavailable (code dependency_unavailable); retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Email": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "value": { "type": "string", "description": "Lowercased matching key" }, "rawValue": { "type": "string" }, "isPrimary": { "type": "boolean" } } }, "Phone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "value": { "type": "string", "description": "E.164 when parseable, else digits" }, "e164": { "type": [ "string", "null" ] }, "rawValue": { "type": "string" }, "isPrimary": { "type": "boolean" } } }, "SocialLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "network": { "type": "string" }, "url": { "type": "string" } } }, "Address": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "The words a person or a file used, such as USA. Kept as written." }, "isPrimary": { "type": "boolean" }, "formatted": { "type": "string" } } }, "Affiliation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "personId": { "type": "string", "format": "uuid" }, "personName": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "companyName": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "startedOn": { "type": [ "string", "null" ], "format": "date" }, "endedOn": { "type": [ "string", "null" ], "format": "date" }, "current": { "type": "boolean" }, "isSample": { "type": "boolean", "description": "True when the role, or the person or company on either side of it, is sample data." } } }, "Consent": { "type": "object", "description": "The newest answer per channel and purpose; the full history is kept.", "properties": { "channel": { "type": "string" }, "purpose": { "type": "string" }, "status": { "enum": [ "granted", "withdrawn" ] }, "source": { "type": "string" }, "recordedAt": { "type": "string", "format": "date-time" } } }, "Person": { "type": "object", "properties": { "schemaVersion": { "const": "vision-directory-person.v1" }, "displayName": { "type": "string" }, "givenName": { "type": [ "string", "null" ] }, "familyName": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid", "description": "The id other apps store to reference this record." }, "isSample": { "type": "boolean", "description": "True for sample data Core added to a new business; it goes when the owner removes sample data." }, "notes": { "type": [ "string", "null" ] }, "preferredChannel": { "type": [ "string", "null" ], "enum": [ "email", "phone", "sms", "post", null ] }, "preferredLanguage": { "type": [ "string", "null" ] }, "doNotContact": { "type": "boolean" }, "primaryEmail": { "type": [ "string", "null" ] }, "primaryPhone": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Email" }, "maxItems": 50 }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" }, "maxItems": 50 }, "socialLinks": { "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" }, "maxItems": 50 }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "maxItems": 50 }, "affiliations": { "type": "array", "items": { "$ref": "#/components/schemas/Affiliation" }, "description": "Current roles first; at most 100 (see affiliationsTotal)." }, "affiliationsTotal": { "type": "integer", "description": "All roles, including any not listed." }, "includesSample": { "type": "boolean", "description": "True when affiliationsTotal counted a role that is sample data." }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/Consent" } }, "extensions": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Keyed by app id, then field key." }, "recordVersion": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Company": { "type": "object", "properties": { "schemaVersion": { "const": "vision-directory-company.v1" }, "name": { "type": "string" }, "legalName": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid", "description": "The id other apps store to reference this record." }, "isSample": { "type": "boolean", "description": "True for sample data Core added to a new business; it goes when the owner removes sample data." }, "notes": { "type": [ "string", "null" ] }, "preferredChannel": { "type": [ "string", "null" ], "enum": [ "email", "phone", "sms", "post", null ] }, "preferredLanguage": { "type": [ "string", "null" ] }, "doNotContact": { "type": "boolean" }, "primaryEmail": { "type": [ "string", "null" ] }, "primaryPhone": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Email" }, "maxItems": 50 }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" }, "maxItems": 50 }, "socialLinks": { "type": "array", "items": { "$ref": "#/components/schemas/SocialLink" }, "maxItems": 50 }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "maxItems": 50 }, "affiliations": { "type": "array", "items": { "$ref": "#/components/schemas/Affiliation" }, "description": "Current roles first; at most 100 (see affiliationsTotal)." }, "affiliationsTotal": { "type": "integer", "description": "All roles, including any not listed." }, "includesSample": { "type": "boolean", "description": "True when affiliationsTotal counted a role that is sample data." }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/Consent" } }, "extensions": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Keyed by app id, then field key." }, "recordVersion": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PersonSummary": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "primaryEmail": { "type": [ "string", "null" ] }, "primaryPhone": { "type": [ "string", "null" ] }, "companies": { "type": [ "string", "null" ] }, "isSample": { "type": "boolean", "description": "True for sample data Core added to a new business; it goes when the owner removes sample data." }, "updatedAt": { "type": "string" } } }, "CompanySummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "primaryEmail": { "type": [ "string", "null" ] }, "primaryPhone": { "type": [ "string", "null" ] }, "peopleCount": { "type": "integer" }, "isSample": { "type": "boolean", "description": "True for sample data Core added to a new business; it goes when the owner removes sample data." }, "includesSample": { "type": "boolean", "description": "True when peopleCount counted a sample person." }, "updatedAt": { "type": "string" } } }, "PersonPage": { "type": "object", "required": [ "items", "nextCursor", "totalCount" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSummary" } }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "integer" }, "includesSample": { "type": "boolean", "description": "True when totalCount, or a peopleCount on any matching row, counted a sample record." } } }, "CompanyPage": { "type": "object", "required": [ "items", "nextCursor", "totalCount" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "integer" }, "includesSample": { "type": "boolean", "description": "True when totalCount, or a peopleCount on any matching row, counted a sample record." } } }, "DuplicateHint": { "type": "object", "properties": { "entityType": { "enum": [ "person", "company" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "matchedOn": { "enum": [ "email", "phone", "name", "domain" ] }, "value": { "type": "string" }, "isSample": { "type": "boolean", "description": "True for sample data Core added to a new business; it goes when the owner removes sample data." } } }, "Deleted": { "type": "object", "properties": { "id": { "type": "string" }, "deletedAt": { "type": [ "string", "null" ] } } }, "ChangeEvent": { "type": "object", "description": "Events about sample data never appear in the feed. A sample record a person changed and the owner chose to keep appears then, as created (detail.fromSample).", "properties": { "sequence": { "type": "integer" }, "type": { "type": "string", "examples": [ "person.created", "company.updated", "affiliation.linked" ] }, "entityType": { "enum": [ "person", "company", "affiliation" ] }, "entityId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "actorSubject": { "type": "string" }, "actingFor": { "type": [ "string", "null" ], "description": "The person an App said it was acting for: a name, never a contact value." }, "detail": { "type": "object", "description": "Names of what changed and related ids; never contact values." } } }, "CommandEnvelope": { "type": "object", "required": [ "schemaVersion", "commandType", "idempotencyKey" ], "properties": { "schemaVersion": { "const": "vision-directory-command.v1" }, "commandType": { "enum": [ "person.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.record" ] }, "idempotencyKey": { "type": "string" } }, "additionalProperties": true }, "Error": { "type": "object", "description": "Every error, including unknown paths (404 not_found), malformed JSON (400 invalid_request), an oversized body (413) and an unsupported content type (415), uses this envelope; the X-Request-ID response header equals error.requestId. retryable is true only for dependency_unavailable.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "schemaVersion", "code", "message", "requestId", "retryable", "fieldIssues" ], "properties": { "schemaVersion": { "const": "vision-directory-error.v1" }, "code": { "type": "string", "enum": [ "authentication_required", "invalid_credential", "permission_denied", "not_found", "invalid_request", "payload_too_large", "unsupported_media_type", "conflict", "stale_version", "idempotency_conflict", "sample_record_outbound_blocked", "dependency_unavailable", "internal_error" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "fieldIssues": { "type": "array", "items": { "type": "object" } } } } } } } } }