ncino-docman

nCino DocMan — Upload via Placeholder API

How to save a generated document (typically a credit memo PDF) to nCino DocMan as a proper placeholder — not as a generic Salesforce File. This is the system-of-record write path that the credit committee expects.

Why use the Placeholder API and not basic Salesforce Files

Basic ContentVersion + ContentDocumentLink only attaches the file to a record. It puts the document in the "Files" related list but does NOT register it in nCino's DocMan view. DocMan is a layer on top of Salesforce Files with its own placeholder model, audit history, and category taxonomy. Credit committee reviewers go to the DocMan tab — files in the generic Files list are invisible to them.

The Placeholder API at /services/apexrest/NDOC/api/v1/document-management/placeholders/* is the correct write path. It both registers the placeholder in DocMan AND wires up the underlying ContentVersion. Use it.

When this applies

• Saving a credit memo PDF to the Product Package's DocMan
• Saving any other generated artifact (BBC, covenant compliance certificate, term sheet) to a borrower's nCino record
• Refreshing a placeholder with a new document version (memo refresh, BBC update, etc.)

The flow — three steps, one API call each

Demo assumption: the PDF is already rendered. This skill does NOT handle HTML→PDF rendering — that's environmental (Chrome headless on macOS, weasyprint in a properly-provisioned Cowork sandbox, hosted service, etc.). Render upstream; this skill picks up the PDF and pushes it into nCino.

Step 0 — Salesforce instance URL (hardcoded for this demo)

For this demo, the Salesforce instance URL is hardcoded to the Accenture BankingGPT sandbox (per CLAUDE.md):

https://accenture-d8--bankinggpt.sandbox.lightning.force.com

Use this literal base for every API call and every Lightning record link. Do NOT call getUserInfo, do NOT ask the user for an instance URL.

URL pattern for all Lightning record links:

https://accenture-d8--bankinggpt.sandbox.lightning.force.com/lightning/r/{ObjectApiName}/{RecordId}/view

(In production, this gets swapped back to env/connector resolution.)

Step 1 — Upload the PDF as a Salesforce ContentVersion

POST {instanceUrl}/services/data/v60.0/sobjects/ContentVersion
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "Title": "{Borrower} - Commercial Credit Memo - {YYYY-MM-DD}",
  "PathOnClient": "{borrower-slug}-credit-memo-{YYYY-MM-DD}.pdf",
  "VersionData": "{base64-encoded PDF bytes}"
}

Capture Id from response (starts with 068...) — that's the ContentVersion Id you'll need for Step 3.

Notes:

• Do NOT include FirstPublishLocationId here. If you set it, Salesforce auto-creates a ContentDocumentLink to that record, dropping the file into the generic "Files" related list. That's the WRONG path for DocMan. Leave FirstPublishLocationId out — Step 3's placeholders/create call wires up the linkage correctly.
• For binary PDFs, VersionData must be base64-encoded. Read the file binary, base64-encode, embed in the JSON string.

Step 2 — Look up the right DocType ID for the target object and category

Each Doc Type record (LLC_BI__DocType__c) is scoped to a specific Document Manager (LLC_BI__DocManager__c), which is in turn scoped to a parent object type (LLC_BI__Type__c, e.g., LLC_BI__Product_Package__c).

To find available Doc Types on a Product Package's DocMan:

SELECT Id, Name
FROM LLC_BI__DocType__c
WHERE LLC_BI__DocManager__r.LLC_BI__Type__c = 'LLC_BI__Product_Package__c'
ORDER BY Name

For Loan-level DocMan, change the filter to 'LLC_BI__Loan__c'.

In the BankingGPT (Truist) sandbox specifically — important field-tested convention:

The Product Package "DocMan" tab aggregates loan-level placeholders, not package-level ones. The page renders placeholders whose context is a child LOAN of the package (using the Loan DocManager a3kbb000000aLZ4AAM or the Collateral DocManager a3kbb000000aLZ5AAM). Placeholders attached directly to the Product Package context (using the Product Package DocManager a3kbb000000aLYzAAM) do NOT appear in this view, even though they technically exist on the package record.

Practical implication for credit memo uploads in this org: attach the placeholder to the primary loan (typically the largest by commitment, or the one designated as primary), NOT the Product Package itself. Use the Loan-level "Underwriting" DocType (a3nbb000004uyDxAAI) as the category — that's purpose-built for credit memos.

Available Loan-level DocTypes in this org:

• Closing Documents (a3nbb000004uyE4AAI)
• Compliance (a3nbb000004uyDyAAI)
• Generated Forms (a3nbb000004uyDlAAI)
• Inspection (a3nbb000004uyE5AAI)
• Loan Documents (a3nbb000004uyDwAAI)
• Underwriting (a3nbb000004uyDxAAI) ← use this for credit memos

Available Product Package-level DocTypes (only used if you've confirmed the org renders package-level placeholders in its DocMan view):

• Approval Documents (a3nbb000004uyDjAAI)
• Generated Forms (a3nbb000004uyDnAAI)

In a different org / deployment, the available Doc Types AND the DocMan rendering convention may differ. Always query Doc Types first, and verify which level (Package vs. Loan) the org's DocMan view actually surfaces. Cache the result for the session.

Step 3 — Create the DocMan placeholder and associate the document in one call

The contextIdentity is the PRIMARY LOAN (in BankingGPT — Working Capital line a4Zbb000001vavpEAA is the primary for Piedmont), NOT the Product Package. The DocMan UI renders loan-level placeholders.

POST {instanceUrl}/services/apexrest/NDOC/api/v1/document-management/placeholders/create
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "addNewVersion": true,
  "placeholders": [
    {
      "attributes": {
        "Name": "Credit Memo",
        "category": "{Loan-level Underwriting DocType Id}",
        "contextIdentity": "{Primary Loan Id}"
      },
      "document": {
        "versions": [
          {
            "attributes": {
              "internalContent": "{ContentVersion Id from Step 1}"
            }
          }
        ]
      }
    }
  ]
}

Expected response: HTTP 201 with a single placeholder descriptor. Capture identity (the placeholder ID, starts with a3s...).

The Name field is the display name in the DocMan UI — keep it short and semantic ("Credit Memo", "Annual Review Memo"). Do NOT include date or memo type in the Name — those belong on the ContentVersion.Title instead so the placeholder stays clean across refreshes.

Step 4 — Confirm to the user

The placeholder lives on the primary Loan but appears in the Product Package DocMan tab (because that tab aggregates loan-level placeholders). The user-facing language should match how they'll actually navigate to it — link to the Product Package DocMan tab, even though contextIdentity is the Loan.

Return:

• One sentence: "Saved as a new 'Credit Memo' placeholder under the primary Loan, visible on Product Package {Name}'s DocMan tab."
• A Lightning URL to the Product Package (NOT to the placeholder itself — see citation policy below)
• The ContentVersion ID and placeholder ID inline (no URLs)
• The Loan name + ID inline as well, since that's where the placeholder is technically attached

Example:

Saved piedmont-precision-credit-memo-2026-05-11.pdf as a new "Credit Memo" placeholder under primary Loan Piedmont Precision Working Capital Line (a4Zbb000001vavpEAA), visible on Product Package Piedmont Precision C&I Credit Package's DocMan tab. ContentVersion 068bb00000KLwTjAAL, placeholder a3sbb00000R6yTRAAZ. View at https://accenture-d8--bankinggpt.sandbox.lightning.force.com/lightning/r/LLC_BI__Product_Package__c/{packageId}/view.

Refresh path — when the "Credit Memo" placeholder already exists

If the user has already saved a Credit Memo placeholder for this borrower's primary Loan (e.g., from a prior annual review), don't create a duplicate. Search first, update if found.

Step 2a — Search for an existing placeholder

Search by the primary Loan Id — that's the contextIdentity placeholders live under in this org, not the Product Package Id.

POST {instanceUrl}/services/apexrest/NDOC/api/v1/document-management/placeholders/search
{
  "contextIds": ["{Primary Loan Id}"],
  "loadWithDocuments": false,
  "loadWithDocumentVersions": false,
  "paginationPageNumber": 0,
  "resultsPerPage": 0
}

Iterate the response array, find any placeholder where attributes.Name is "Credit Memo" (case-insensitive). Capture its identity. If you search by Product Package Id you'll get back zero results (because placeholders aren't attached at that level in this org) and the refresh path will silently create a duplicate.

Step 3a — Add the new ContentVersion as a new version of the existing placeholder

POST {instanceUrl}/services/apexrest/NDOC/api/v1/document-management/placeholders/update
{
  "addNewVersion": true,
  "placeholders": [
    {
      "identity": "{Existing Placeholder Id}",
      "document": {
        "versions": [
          {
            "attributes": {
              "internalContent": "{ContentVersion Id from Step 1}"
            }
          }
        ]
      }
    }
  ]
}

addNewVersion: true keeps prior memo versions in the placeholder's history — important for audit trail.

Citation policy — what to link, what to inline

When emitting Salesforce record references in memo output, email drafts, or chat responses:

Link with hyperlinks (using the {instanceUrl}/lightning/r/{ObjectApiName}/{Id}/view pattern):

• The borrower Account
• The LLC_BI__Product_Package__c
• Any LLC_BI__Loan__c records under that Package

Cite by ID inline, NO URL:

• ContentDocument, ContentVersion, ContentDocumentLink
• Boom_File__c, Boom_Financial_Statement__c, Boom_Line_Item__c
• LLC_BI__Account_Covenant__c, LLC_BI__Loan_Collateral2__c, LLC_BI__Legal_Entities__c
• Any other junction object
• The DocMan placeholder itself

Reasoning: files attach to the Account / Product Package / Loan record and are accessed from there via the related lists or DocMan tab. Linking the underlying ContentVersion or junction object takes the user to a generic Salesforce detail page that doesn't fit the credit-officer workflow. Citing the ID inline (e.g., "Boom file a8Qbb0000003d85EAA") gives full traceability for audit / Exhibit D without sending the reviewer down the wrong navigation path.

Example output:

Saved as a new "Credit Memo" placeholder under primary Loan Piedmont Precision Working Capital Line, visible on Product Package Piedmont Precision C&I Credit Package's DocMan tab. Underlying ContentVersion 068bb00000KLwTjAAL, DocMan placeholder a3sbb00000R6yTRAAZ. Sourced from Boom file a8Qbb0000003d85EAA (FYE 12/31/2025).

Failure modes

• Including FirstPublishLocationId in Step 1 — the file ends up in the generic Files related list instead of DocMan. The placeholder in Step 3 still works but you've duplicated the file linkage. Always omit FirstPublishLocationId when using the Placeholder API.
• Querying for a "Credit Memo" Doc Type that doesn't exist — many nCino implementations don't have a Doc Type literally called "Credit Memo". Always query for available types and use the closest semantic match ("Approval Documents", "Credit Documents", "Underwriting Documents", etc.). Don't assume a name.
• Hardcoding a My Domain in URLs — breaks across orgs. Always use the connector's instanceUrl.
• Skipping the DocType lookup — passing an invalid category ID returns HTTP 400. Cache the result of Step 2 for the session and reuse.
• Wrong contextIdentity — passing a Product Package ID when you mean a Loan ID (or vice versa) puts the placeholder on a record that the DocMan UI doesn't surface. In this org (BankingGPT sandbox), credit memos belong on the primary Loan — the Product Package DocMan tab aggregates loan-level placeholders and ignores package-level ones. Use the primary Loan Id as contextIdentity, paired with the loan-level "Underwriting" DocType a3nbb000004uyDxAAI. (See Step 2 for the practical implication and the field-tested rationale.)
• Base64 encoding errors — for binary PDFs, the entire file bytes must be base64-encoded (NOT URL-safe base64). Standard base64 with + and / characters. Use the language's standard base64 encoder.

Quick reference

Step	Method	Endpoint
1. Upload PDF	POST	/services/data/v60.0/sobjects/ContentVersion
2. Query DocTypes	GET	/services/data/v60.0/query/?q=SELECT...
2a. Search existing placeholders	POST	/services/apexrest/NDOC/api/v1/document-management/placeholders/search
3. Create placeholder + link	POST	/services/apexrest/NDOC/api/v1/document-management/placeholders/create
3a. Update existing placeholder	POST	/services/apexrest/NDOC/api/v1/document-management/placeholders/update