A live or soft-deleted client with the same trimmed client_id is updated or restored. Matched clients appear in updated, even when their fields do not change. New clients appear in created.HTTP 200 can include row failures in errors; valid rows still succeed. A repeated identifier in the batch produces duplicate_client_id for the later row.See the Client Matters guide for examples and migration steps.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Harvey","colors":{"primary":"#000000","light":"#FFFFFF","dark":"#000000"},"logo":{"light":"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/logo/Harvey_Logo_Ink.svg?fit=max\u0026auto=format\u0026n=MseNlCOSIs-6XLeD\u0026q=85\u0026s=749bc9fa610e1b9ba2b7ffce7dd5f04a","dark":"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/logo/Harvey_Logo_Ivory.svg?fit=max\u0026auto=format\u0026n=MseNlCOSIs-6XLeD\u0026q=85\u0026s=d8d9762153d411d19bcd8a8e17d4d5d3"},"favicon":"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/Harvey_Glyph.svg?fit=max\u0026auto=format\u0026n=MseNlCOSIs-6XLeD\u0026q=85\u0026s=0b2b40a43d7c86d305d6d3fc2501444c","api":{"playground":{"display":"simple"}},"navbar":{"links":[{"href":"mailto:support@harvey.ai","label":"Contact Support"}],"primary":{"type":"button","label":"app.harvey.ai","href":"https://app.harvey.ai"}},"footer":{"socials":{"linkedin":"https://linkedin.com/company/harvey-ai","twitter":"https://x.com/harvey_ai"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"counselai","hasAudioNarration":false,"actualSubdomain":"counselai","customDomains":["developers.harvey.ai"],"gitSource":{"type":"github","owner":"harveyai","repo":"public-api-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6aee594cb616b538027e966e","clientVersion":"0.0.4088","searchFilterCounts":[{"language":"default","tag":"API Reference","count":39},{"language":"default","tag":"Vault","count":32},{"language":"default","tag":"Guides","count":11},{"language":"default","tag":"Intake","count":10},{"language":"default","tag":"Endpoint Overview","count":8},{"language":"default","tag":"Client Matters","count":7},{"language":"default","tag":"Getting Started","count":4},{"language":"default","tag":"Audit Logs","count":4},{"language":"default","tag":"History Export","count":4},{"language":"default","tag":"Delete","count":3}],"searchSettings":{"showContentSnippets":true,"isFiltersEnabled":false}},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":false}},"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/upsert/upsert-clients","slug":"/api-reference/upsert/upsert-clients","pageMetadata":{"title":"Upsert Clients","description":"Creates or updates clients using your firm's client identifiers. Submit 1 to 10,000 clients per request.","deprecated":null,"version":null,"openapi":"/client_matters_api.json post /api/v2/clients","href":"/api-reference/upsert/upsert-clients","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Creates or updates clients using your firm’s client identifiers. Submit 1 to 10,000 clients per request.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,strong:`strong`,..._provideComponents(),...props.components},{Heading}=_components;if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`3`,id:`permissions`,children:`Permissions`}),`\n`,_jsxs(_components.p,{children:[`Requires `,_jsx(_components.strong,{children:`Client matters admin`}),` (`,_jsx(_components.code,{children:`write:client_matters`}),`).`]}),`\n`,_jsx(Heading,{level:`3`,id:`matching-and-results`,children:`Matching and results`}),`\n`,_jsxs(_components.p,{children:[`A live or soft-deleted client with the same trimmed `,_jsx(_components.code,{children:`client_id`}),` is updated or restored. Matched clients appear in `,_jsx(_components.code,{children:`updated`}),`, even when their fields do not change. New clients appear in `,_jsx(_components.code,{children:`created`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`HTTP 200 can include row failures in `,_jsx(_components.code,{children:`errors`}),`; valid rows still succeed. A repeated identifier in the batch produces `,_jsx(_components.code,{children:`duplicate_client_id`}),` for the later row.`]}),`\n`,_jsxs(_components.p,{children:[`See the `,_jsx(_components.a,{href:`/guides/client_matters`,children:`Client Matters guide`}),` for examples and migration steps.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Upsert Clients","description":"Creates or updates clients using your firm's client identifiers. Submit 1 to 10,000 clients per request.","deprecated":null,"version":null,"openapi":"/client_matters_api.json post /api/v2/clients","href":"/api-reference/upsert/upsert-clients","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Permissions","slug":"permissions","depth":3,"children":[]},{"title":"Matching and results","slug":"matching-and-results","depth":3,"children":[]}],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Upsert Clients","description":"Creates or updates clients using your firm's client identifiers. Submit 1 to 10,000 clients per request.","operationId":"upsertClients","tags":["Upsert"],"requestBody":"5326edae-9c4b-48e6-a599-0d690a82317a","responses":{"200":"cf6d200d-a45f-40e0-a4af-0d284f007afd","400":"3e025e22-f446-45e0-a8a2-546faafe37be","401":"52d91dd2-3b39-4db7-af7d-97fc978fb478","403":"74cd49f3-9ffb-4046-9173-a892ef97a541","429":"a95d6399-7e82-4ea2-aeab-6f1507036959","500":"9fbec728-042e-444d-a754-b27b992223be"},"security":["773f4e03-f097-4603-9646-bf3366dfe699"],"x-mint":{"content":"### Permissions\nRequires **Client matters admin** (`write:client_matters`).\n\n### Matching and results\nA live or soft-deleted client with the same trimmed `client_id` is updated or restored. Matched clients appear in `updated`, even when their fields do not change. New clients appear in `created`.\n\nHTTP 200 can include row failures in `errors`; valid rows still succeed. A repeated identifier in the batch produces `duplicate_client_id` for the later row.\n\nSee the [Client Matters guide](/guides/client_matters) for examples and migration steps."},"method":"post","type":"path","servers":["f8d2a04c-d892-4674-ae84-73ebeba47e6e"],"path":"/api/v2/clients","baseUrlOptions":["https://api.harvey.ai"],"title":"Upsert Clients","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clients"],"properties":{"clients":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"object","description":"One client keyed on the firm's client identifier. Omit `client_name` to leave the stored label unchanged. Send null or a blank string to clear it. Values are stripped.","required":["client_id"],"properties":{"client_id":{"type":"string","description":"The firm's client identifier, the upsert key within the workspace. Not the Harvey client UUID that `GET /api/v1/client_matters` returns in its own `client_id` field. Empty after stripping, or over 128 characters, fails per row with `invalid_client_id`.","isRequired":true,"uniqueKey":"clients.items.[INDEX].client_id","typeLabel":"string"},"client_name":{"oneOf":[{"type":"string","description":"Friendly label for the client. Over 256 characters fails per row with `invalid_client_name`.","uniqueKey":"clients.items.[INDEX].client_name.oneOf.0","typeLabel":"string"},{"type":"null","description":"Friendly label for the client. Over 256 characters fails per row with `invalid_client_name`.","uniqueKey":"clients.items.[INDEX].client_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"clients.items.[INDEX].client_name","typeLabel":"string | null"}},"uniqueKey":"clients.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"clients","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"example":{"clients":[{"client_id":"10022421","client_name":"Acme Corp"}]},"examples":{"Example":{"title":"Example","value":{"clients":[{"client_id":"10022421","client_name":"Acme Corp"}]}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"cf6d200d-a45f-40e0-a4af-0d284f007afd":{"description":"Per-row results for the submitted clients.","content":{"application/json":{"schema":{"type":"object","required":["created","updated","errors"],"properties":{"created":{"type":"array","items":{"type":"object","required":["client_id","client_name"],"properties":{"client_id":{"type":"string","description":"The stored, stripped firm client identifier.","isRequired":true,"uniqueKey":"created.items.[INDEX].client_id","typeLabel":"string"},"client_name":{"oneOf":[{"type":"string","description":"The stored label after this request.","isRequired":true,"uniqueKey":"created.items.[INDEX].client_name.oneOf.0","typeLabel":"string"},{"type":"null","description":"The stored label after this request.","isRequired":true,"uniqueKey":"created.items.[INDEX].client_name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"created.items.[INDEX].client_name","typeLabel":"string | null"}},"uniqueKey":"created.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"created","typeLabel":"object[]"},"updated":{"type":"array","description":"Includes restored clients and matched clients whose fields did not change.","items":{"type":"object","required":["client_id","client_name"],"properties":{"client_id":{"type":"string","description":"The stored, stripped firm client identifier.","isRequired":true,"uniqueKey":"updated.items.[INDEX].client_id","typeLabel":"string"},"client_name":{"oneOf":[{"type":"string","description":"The stored label after this request.","isRequired":true,"uniqueKey":"updated.items.[INDEX].client_name.oneOf.0","typeLabel":"string"},{"type":"null","description":"The stored label after this request.","isRequired":true,"uniqueKey":"updated.items.[INDEX].client_name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"updated.items.[INDEX].client_name","typeLabel":"string | null"}},"uniqueKey":"updated.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"updated","typeLabel":"object[]"},"errors":{"type":"array","items":{"type":"object","required":["client_id","error","detail"],"properties":{"client_id":{"type":"string","description":"Echoes the raw request value.","isRequired":true,"uniqueKey":"errors.items.[INDEX].client_id","typeLabel":"string"},"error":{"type":"string","description":"Stable code for a client row that was not stored. `invalid_client_id`: `client_id` is empty after stripping or over 128 characters. `invalid_client_name`: `client_name` is over 256 characters. `duplicate_client_id`: a later entry repeats an earlier `client_id` after stripping; the first entry wins.","enum":["invalid_client_id","invalid_client_name","duplicate_client_id"],"isRequired":true,"uniqueKey":"errors.items.[INDEX].error","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Human-readable explanation.","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"errors","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"created":{"title":"created","value":{"created":[{"client_id":"10022421","client_name":"Acme Corp"}],"updated":[],"errors":[]}},"updated":{"title":"updated","value":{"created":[],"updated":[{"client_id":"10022421","client_name":"Acme Corp"}],"errors":[]}},"partialSuccess":{"title":"partialSuccess","value":{"created":[{"client_id":"10022421","client_name":"Acme Corp"}],"updated":[],"errors":[{"client_id":" ","error":"invalid_client_id","detail":"Client identifier must not be empty"}]}}},"exampleType":"examples"}},"exampleType":"examples"},"3e025e22-f446-45e0-a8a2-546faafe37be":{"description":"The request was rejected as a whole.","content":{"application/json":{"schema":{"type":"object","description":"Body of a 400 response from `/api/v2/clients` and `/api/v2/matters`.","required":["error","detail"],"properties":{"error":{"type":"string","description":"Stable code for a rejected request. too_many_items: more than 10,000 rows. invalid_request: invalid request shape, empty batch, missing required field, wrong type, allowed set to null, or a token user that cannot be found. delimiter_required: POST /api/v2/matters requires an explicit delimiter for the active workspace, but none is configured. Other workspaces use `.` when no delimiter is configured. POST /api/v2/clients, DELETE /api/v2/clients, and DELETE /api/v2/matters do not emit delimiter_required. Duplicate identifiers and length limits on text fields produce per-row errors instead.","enum":["too_many_items","invalid_request","delimiter_required"],"isRequired":true,"uniqueKey":"error","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Human-readable explanation.","isRequired":true,"uniqueKey":"detail","typeLabel":"string"},"validation_errors":{"type":"array","description":"Present for `invalid_request`. Field values are never echoed.","items":{"type":"object","required":["loc","type"],"properties":{"loc":{"type":"array","description":"Path to the offending field. Each entry is a string naming a field or an integer indexing an array.","items":{"oneOf":[{}],"uniqueKey":"validation_errors.items.[INDEX].loc.items.[INDEX]","typeLabel":"any"},"isRequired":true,"uniqueKey":"validation_errors.items.[INDEX].loc","typeLabel":"any[]"},"type":{"type":"string","description":"The validation failure kind, for example `missing` or `string_type`.","isRequired":true,"uniqueKey":"validation_errors.items.[INDEX].type","typeLabel":"string"}},"uniqueKey":"validation_errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"validation_errors","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"invalid_request","detail":"Invalid request body","validation_errors":[{"loc":["clients"],"type":"too_short"}]},"examples":{"Example":{"title":"Example","value":{"error":"invalid_request","detail":"Invalid request body","validation_errors":[{"loc":["clients"],"type":"too_short"}]}}},"exampleType":"examples"}},"exampleType":"examples"},"52d91dd2-3b39-4db7-af7d-97fc978fb478":{"description":"Missing, invalid, or expired API token, or missing write:client_matters permission.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"74cd49f3-9ffb-4046-9173-a892ef97a541":{"description":"Forbidden.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"a95d6399-7e82-4ea2-aeab-6f1507036959":{"description":"Rate limit exceeded. These endpoints share the client matter rate limit, which defaults to 150 requests per minute per workspace.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"9fbec728-042e-444d-a754-b27b992223be":{"description":"Internal server error.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}}},"security":{"773f4e03-f097-4603-9646-bf3366dfe699":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Token","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"f8d2a04c-d892-4674-ae84-73ebeba47e6e":{"url":"https://api.harvey.ai","description":"Harvey API server"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","bearerFormat":"Token","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"client_matters_api.json"},"subdomain":"counselai","siteName":"Harvey","title":"Upsert Clients - Harvey","relatedPagesConfig":{"enabled":true,"limit":3,"mode":"automatic"},"navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-28T23:06:24.208Z","originalFileLocation":"api-reference/upsert/upsert-clients.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Creates or updates clients using your firm\u0026#x27;s client identifiers. Submit 1 to 10,000 clients per request.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Harvey\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/svg+xml\" sizes=\"180x180\" href=\"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/Harvey_Glyph.svg?fit=max\u0026amp;auto=format\u0026amp;n=MseNlCOSIs-6XLeD\u0026amp;q=85\u0026amp;s=0b2b40a43d7c86d305d6d3fc2501444c\">\u003clink data-mint-head rel=\"icon\" type=\"image/svg+xml\" sizes=\"32x32\" href=\"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/Harvey_Glyph.svg?fit=max\u0026amp;auto=format\u0026amp;n=MseNlCOSIs-6XLeD\u0026amp;q=85\u0026amp;s=0b2b40a43d7c86d305d6d3fc2501444c\">\u003clink data-mint-head rel=\"icon\" type=\"image/svg+xml\" sizes=\"16x16\" href=\"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/Harvey_Glyph.svg?fit=max\u0026amp;auto=format\u0026amp;n=MseNlCOSIs-6XLeD\u0026amp;q=85\u0026amp;s=0b2b40a43d7c86d305d6d3fc2501444c\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/svg+xml\" href=\"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/Harvey_Glyph.svg?fit=max\u0026amp;auto=format\u0026amp;n=MseNlCOSIs-6XLeD\u0026amp;q=85\u0026amp;s=0b2b40a43d7c86d305d6d3fc2501444c\">\u003cmeta data-mint-head property=\"og:title\" content=\"Upsert Clients - Harvey\">\u003cmeta data-mint-head property=\"og:description\" content=\"Creates or updates clients using your firm\u0026#x27;s client identifiers. Submit 1 to 10,000 clients per request.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Harvey\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developers.harvey.ai/api-reference/upsert/upsert-clients\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://counselai.mintlify.site/_mintlify/api/og/v2?division=Upsert\u0026amp;title=Upsert+Clients\u0026amp;description=Creates+or+updates+clients+using+your+firm%27s+client+identifiers.+Submit+1+to+10%2C000+clients+per+request.\u0026amp;theme=ca09a866a969d63910536c2f\u0026amp;signature=57eb7b0e748653ec0037a32d216a9045bad7c2e58a4527f1f3bc696d2f05fbbe\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Upsert Clients - Harvey\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Creates or updates clients using your firm\u0026#x27;s client identifiers. Submit 1 to 10,000 clients per request.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://counselai.mintlify.site/_mintlify/api/og/v2?division=Upsert\u0026amp;title=Upsert+Clients\u0026amp;description=Creates+or+updates+clients+using+your+firm%27s+client+identifiers.+Submit+1+to+10%2C000+clients+per+request.\u0026amp;theme=ca09a866a969d63910536c2f\u0026amp;signature=57eb7b0e748653ec0037a32d216a9045bad7c2e58a4527f1f3bc696d2f05fbbe\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/counselai/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Harvey\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#000000\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developers.harvey.ai/api-reference/upsert/upsert-clients\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/upsert/upsert-clients.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developers.harvey.ai/#organization\",\"name\":\"Harvey\",\"url\":\"https://developers.harvey.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/counselai/MseNlCOSIs-6XLeD/logo/Harvey_Logo_Ink.svg?fit=max\u0026auto=format\u0026n=MseNlCOSIs-6XLeD\u0026q=85\u0026s=749bc9fa610e1b9ba2b7ffce7dd5f04a\"}},{\"@type\":\"WebSite\",\"@id\":\"https://developers.harvey.ai#website\",\"name\":\"Harvey\",\"url\":\"https://developers.harvey.ai\",\"publisher\":{\"@id\":\"https://developers.harvey.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients#webpage\",\"url\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients\",\"name\":\"Upsert Clients\",\"description\":\"Creates or updates clients using your firm's client identifiers. Submit 1 to 10,000 clients per request.\",\"dateModified\":\"2026-10-28T23:06:24.208Z\",\"isPartOf\":{\"@id\":\"https://developers.harvey.ai#website\"},\"breadcrumb\":{\"@id\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Client Matters\",\"item\":\"https://developers.harvey.ai/api-reference/retrieve/get-client-matters\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Upsert Clients\",\"item\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients#apireference\",\"headline\":\"Upsert Clients\",\"name\":\"Upsert Clients\",\"description\":\"Creates or updates clients using your firm's client identifiers. Submit 1 to 10,000 clients per request.\",\"url\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients\",\"mainEntityOfPage\":{\"@id\":\"https://developers.harvey.ai/api-reference/upsert/upsert-clients#webpage\"},\"dateModified\":\"2026-10-28T23:06:24.208Z\",\"publisher\":{\"@id\":\"https://developers.harvey.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://developers.harvey.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Harvey\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Harvey","nav":{"global":null,"tabs":[{"tab":"API Reference","groups":[{"group":"Getting Started","pages":[{"title":"Authentication","href":"/api-reference/authentication"},{"title":"Rate Limits","href":"/api-reference/ratelimits"}]},{"group":"Assistant","pages":[{"group":"Completion","pages":[{"title":"Completion","deprecated":null,"version":null,"openapi":"/v2_completion_api.json post /api/v2/completion","href":"/api-reference/completion/completion"}]}]},{"group":"Vault","pages":[{"group":"Vault","pages":[{"title":"List Vault Projects and Knowledge Bases","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/workspace/projects","href":"/api-reference/vault/list-vault-projects-and-knowledge-bases"},{"title":"List Vaults in the Recycle Bin","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/workspace/recycle_bin","href":"/api-reference/vault/list-vaults-in-the-recycle-bin"},{"title":"Get Vault Project Metadata","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/get_metadata/{project_id}","href":"/api-reference/vault/get-vault-project-metadata"},{"title":"Get Review Table Metadata","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/review_table/{review_table_id}","href":"/api-reference/vault/get-review-table-metadata"},{"title":"Get File Details","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/get_files","href":"/api-reference/vault/get-file-details"},{"title":"Get Review Table Row Details","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/get_row/{review_table_id}/{file_id}","href":"/api-reference/vault/get-review-table-row-details"},{"title":"Add Row to Review Table","deprecated":null,"version":null,"openapi":"/vault_api.json post /api/v1/vault/add_row/{review_table_id}","href":"/api-reference/vault/add-row-to-review-table"},{"title":"List Files in a Vault Project","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/projects/{project_id}/files","href":"/api-reference/vault/list-files-in-a-vault-project"},{"title":"List Project Users","deprecated":null,"version":null,"openapi":"/vault_api.json get /api/v1/vault/projects/{project_id}/users","href":"/api-reference/vault/list-project-users"},{"title":"Update Project Users","deprecated":null,"version":null,"openapi":"/vault_api.json post /api/v1/vault/projects/{project_id}/users","href":"/api-reference/vault/update-project-users"},{"title":"Remove Project Users","deprecated":null,"version":null,"openapi":"/vault_api.json delete /api/v1/vault/projects/{project_id}/users","href":"/api-reference/vault/remove-project-users"},{"title":"Create a new Vault project","deprecated":null,"version":null,"openapi":"/vault_api.json post /api/v1/vault/create_project","href":"/api-reference/vault/create-a-new-vault-project"},{"title":"Upload Files to Project","deprecated":null,"version":null,"openapi":"/vault_api.json post /api/v1/vault/upload_files/{project_id}","href":"/api-reference/vault/upload-files-to-project"},{"title":"Semantic search over a vault project","deprecated":null,"version":null,"openapi":"/vault_api.json post /api/v1/vault/semantic_search","href":"/api-reference/vault/semantic-search-over-a-vault-project"},{"title":"Delete a file from a Vault project","deprecated":null,"version":null,"openapi":"/vault_api.json delete /api/v1/vault/delete_file/{file_id}","href":"/api-reference/vault/delete-a-file-from-a-vault-project"},{"title":"Delete an entire vault project and all its contents","deprecated":null,"version":null,"openapi":"/vault_api.json delete /api/v1/vault/delete_project/{project_id}","href":"/api-reference/vault/delete-an-entire-vault-project-and-all-its-contents"}]}]},{"group":"History Export","pages":[{"group":"Usage","pages":[{"title":"Get Usage History","deprecated":null,"version":null,"openapi":"/history_export_api.json get /api/v1/history/usage","href":"/history-export/usage/get-usage-history"},{"title":"Get Usage History (v2)","deprecated":null,"version":null,"openapi":"/history_export_api.json get /api/v2/history/usage","href":"/history-export/usage/get-usage-history-v2"}]},{"group":"Queries","pages":[{"title":"Get Query History","deprecated":null,"version":null,"openapi":"/history_export_api.json get /api/v1/history/query","href":"/history-export/queries/get-query-history"},{"title":"Get Query History (v2)","deprecated":null,"version":null,"openapi":"/history_export_api.json get /api/v2/history/query","href":"/history-export/queries/get-query-history-v2"}]}]},{"group":"Audit Logs","pages":[{"group":"Search","pages":[{"title":"Search Audit Logs","deprecated":null,"version":null,"openapi":"/audit_logs_api.json get /api/v1/logs/audit/search/","href":"/api-reference/search/search-audit-logs"}]},{"group":"Retrieve","pages":[{"title":"Retrieve Earliest Audit Log","deprecated":null,"version":null,"openapi":"/audit_logs_api.json get /api/v1/logs/audit/earliest","href":"/api-reference/retrieve/retrieve-earliest-audit-log"},{"title":"Retrieve Latest Audit Log","deprecated":null,"version":null,"openapi":"/audit_logs_api.json get /api/v1/logs/audit/latest","href":"/api-reference/retrieve/retrieve-latest-audit-log"}]},{"group":"Query","pages":[{"title":"Query Audit Logs","deprecated":null,"version":null,"openapi":"/audit_logs_api.json get /api/v1/logs/audit","href":"/api-reference/query/query-audit-logs"}]}]},{"group":"Client Matters","pages":[{"group":"Retrieve","pages":[{"title":"Get Client Matters","deprecated":null,"version":null,"openapi":"/client_matters_api.json get /api/v1/client_matters","href":"/api-reference/retrieve/get-client-matters"}]},{"group":"Add","pages":[{"title":"Add Client Matters","deprecated":true,"version":null,"openapi":"/client_matters_api.json post /api/v1/client_matters","href":"/api-reference/add/add-client-matters"}]},{"group":"Delete","pages":[{"title":"Delete Client Matters","deprecated":null,"version":null,"openapi":"/client_matters_api.json delete /api/v1/client_matters","href":"/api-reference/delete/delete-client-matters"},{"title":"Delete Clients","deprecated":null,"version":null,"openapi":"/client_matters_api.json delete /api/v2/clients","href":"/api-reference/delete/delete-clients"},{"title":"Delete Matters","description":"Soft-deletes matters by your firm's client and matter identifiers. Submit 1 to 10,000 pairs per request. Each pair receives one result in deleted, already_absent, or errors. Inspect errors even when the response is HTTP 200. Missing and already-deleted matters appear in already_absent. Externally linked matters cannot be deleted while ethical-wall enforcement is enabled. The parent client is kept.\n\nDeleting a matter does not delete historical queries associated with that matter, nor does it remove the matter from those historical queries.","deprecated":null,"version":null,"openapi":"/client_matters_api.json delete /api/v2/matters","href":"/api-reference/delete/delete-matters"}]},{"group":"Upsert","pages":[{"title":"Upsert Clients","deprecated":null,"version":null,"openapi":"/client_matters_api.json post /api/v2/clients","href":"/api-reference/upsert/upsert-clients"},{"title":"Upsert Matters","description":"Creates or updates matters under existing clients using your firm's client and matter identifiers. Submit 1 to 10,000 matters per request. Uses the delimiter configured for the API token's active workspace, or `.` when none is configured. If the workspace requires an explicit delimiter and none is configured, the whole request returns HTTP 400 with delimiter_required.","deprecated":null,"version":null,"openapi":"/client_matters_api.json post /api/v2/matters","href":"/api-reference/upsert/upsert-matters"}]}]},{"group":"Intake","pages":[{"group":"Intake","pages":[{"title":"List Requests","deprecated":null,"version":null,"openapi":"/intake_api.json get /api/v1/intake/requests","href":"/api-reference/intake/list-requests"},{"title":"Create Request","deprecated":null,"version":null,"openapi":"/intake_api.json post /api/v1/intake/requests","href":"/api-reference/intake/create-request"},{"title":"Get Request","deprecated":null,"version":null,"openapi":"/intake_api.json get /api/v1/intake/requests/{request_id}","href":"/api-reference/intake/get-request"},{"title":"Update Request","deprecated":null,"version":null,"openapi":"/intake_api.json patch /api/v1/intake/requests/{request_id}","href":"/api-reference/intake/update-request"},{"title":"List Comments","deprecated":null,"version":null,"openapi":"/intake_api.json get /api/v1/intake/requests/{request_id}/comments","href":"/api-reference/intake/list-comments"}]}]}]},{"tab":"Guides","pages":[{"title":"Guides","href":"/guides/introduction"}]}]},"basePath":"","title":"Upsert Clients - Harvey","buildId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","deploymentId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-5FCzAcfS.js","utils-SLtAG4EZ.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-2DZi8ZMu.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-D7J3nkzE.js","snippetPresets-D0Alv0AH.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BI4qNJ2c.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BD3uyr8j.js","shallow-D8iEBr5z.js","getApiPlaygroundDisplay-CgNP4lzR.js","CodeSnippet-CX-QHuMs.js","CodeSnippets-VlXE-ZUf.js","Page-D9ithiIZ.js","getPastedJson-DYNQkZ1M.js","icon-CzacdwOi.js","MethodPill-2JVqoYKi.js","DuplicateIcon-_xVXs-U8.js","createIcon-BRHrweLo.js","DynamicMarkdown-mQG_iQiE.js","SectionHeading-DMpJzv8f.js","axios-vUo_bRtp.js","Markdown-5FGIym-8.js","clsx-D-TRO5q5.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CdrJecqK.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CHlcWBLM.js"]}