Partner Integration Guide

This guide explains how to integrate your application with Nocarta using the Partner API. Partners can embed Nocarta forms in their applications, prefill fields with data they already have, and receive callbacks when forms are submitted.

---

Use Cases: Why Integrate Nocarta

Your users still deal with paper. Invoices, contracts, compliance forms, receipts, inspection reports — they type data from documents into your application every day. It's slow, error-prone, and expensive.

Nocarta turns that paper into structured data automatically. Partner Integration lets you add that capability to your application — transparently, without rebuilding anything.

For Managers

Here's what changes when you integrate Nocarta:

1. Your end users stop typing from paper. They photograph the document, Nocarta reads it, and the data arrives in your system — validated, structured, ready to use. Fewer errors, faster turnaround.
2. Your team stops adjusting data. Fields are validated at input: dates are dates, currencies have two decimals, required fields can't be skipped, reference lists offer autocomplete with AI-powered search. Data arrives clean.
3. Manual uploads become automatic. Instead of "download the PDF, open it, copy each field" — users point a camera, and Nocarta does the rest. Multi-page documents, handwritten text, tilted photos — all handled.
4. You get cutting-edge technology without the stack behind it. Text extraction engines, AI extraction, encrypted storage, document preparation pipelines, automation, multi-language support — all running, all maintained. You don't hire for it, you don't build it, you don't manage it.
5. You skip months of implementation. The integration takes minutes of developer time. No new infrastructure, no new databases, no new teams. Your application adds one redirect and one callback — that's the entire technical change.

Nocarta is a new way to use a traditional interface — paper — in a modern AI world. Your users keep working with the documents they know. Your application gets the structured data it needs. The gap between paper and digital disappears.

How technical is the integration?

You don't need to understand the technology to manage it. The setup is done through Nocarta's web interface: you upload a sample of your paper document, Nocarta builds the digital version, and you enable partner mode. From that point on, your application can send users to fill or scan that document, and receive structured data back.

A developer needs about 15 minutes to connect your application. After that, adding new document types is entirely in the manager's hands — no code changes needed.

For Developers

Nocarta offers two integration flows. None of them log a user in on your behalf. Every server-to-server call authenticates with your own API key (a Bearer token you create in Settings → Profile and Connections); the end user fills the form without any Nocarta login, or with their own login.

1. Server post + capability link (most common): Your backend POSTs to /api/v1/partners/:id/instances with Authorization: Bearer <api_key>, and Nocarta returns a one-time fill_url. You send the end user to that link; they fill the form without logging in. The instance is created unaccepted — only the end user can accept it later. Any stack that can make an HTTPS POST integrates in minutes.
2. Redirect-with-reference (Flow B): Your application redirects the browser straight to the form's short link with reference parameters in the URL (/f/:short_code?ref[key]=value&callback=…). The end user self-fills (anonymously, or signed in with their own account) and is redirected back to your callback with the resulting instance ID. No token, no API key in the browser.

The full technical reference starts at Quick Start below. For server-to-server integration, see API-Only Integration.

---

What Your Application Gains

Your Users Can	What Happens Behind the Scenes
Photograph any document and get structured data back	Text extraction reads the document, extracts fields by type, aligns tilted or rotated images, and returns validated data — no manual typing.
Turn any paper form into a digital one instantly	Upload a photo of the form and Nocarta generates a fillable digital version automatically, including multi-page documents. No template building required.
Fill forms with zero data entry errors	Every field is validated by type: dates, currencies, emails, phone numbers. Required fields can't be skipped. Dropdowns offer autocomplete from reference lists with AI-powered search that finds "heart medicine" when the list says "cardiovascular drugs".
Pre-fill forms with data your system already has	Your application sends known values (customer name, account number, address) in the API request, or as reference parameters on the form link. Users only fill what's missing — no re-typing data you already have.
Work with sensitive data safely	Two-tier encryption: server-protected for automation, client-protected for data the server itself cannot decrypt. Field-level granularity — encrypt only what matters.
Process documents in bulk	Document preparation pipelines handle batch operations: split, merge, watermark, extract pages, convert formats — 14 operations, accessible via UI or API.
Automate repetitive document tasks	Multi-step automations with browser automation, AI assistant that builds steps from natural language, and secret injection for credential-protected systems — all executed on the user's device, never on the server.
Convert diagrams into working configurations	Photograph a flowchart or process map and Nocarta generates an automation, form template, or processing recipe from it.
Work in their own language	Full interface in 9 languages: English, German, Spanish, French, Italian, Portuguese, Chinese, Korean, and Japanese.

---

How It Works

Option A: Server post + capability link (your backend creates the instance, the user fills it)

1. Your app authenticates the user — you control who gets access
2. Your backend POSTs to Nocarta at /api/v1/partners/:id/instances (your template's id in the URL) with Authorization: Bearer <api_key> and any prefilled values (plus subscriber_email for B2B2C)
3. Nocarta returns a one-time fill_url and creates the instance unaccepted
4. You send the user to fill_url — they complete the document task (fill, review) without logging in
5. Your app receives a callback with structured results and the instance ID; the end user accepts the instance to take ownership

Option B: Redirect-with-reference (the browser goes straight to the form)

1. Your app redirects the browser to the form short link with ref[…] parameters, a callback, and a state string
2. The user self-fills — anonymously, or signed in with their own Nocarta account
3. The browser is redirected back to your callback with nocarta_instance_id, status=submitted, and your partner_state
4. No token and no API key ever touch the browser

You Keep	Nocarta Handles
User authentication & access control	Document capture & text extraction
Business logic & decision rules	Intelligent form rendering & validation
Final data storage in your database	Field-level encryption (AES-256-GCM)
Your UI and user experience	Image alignment & quality optimization
Billing & subscription management	Automation & multi-step processes
Customer communication	Value set search, AI fill, document preparation

---

Architecture Overview

┌─────────────────────┐   Bearer API key   ┌─────────────────────┐
│   Your Application  │  (server-to-server)│      Nocarta        │
│   (Legacy or New)   │ ────────────────▶  │   Document Engine   │
│                     │                    │                     │
│   • User auth       │ ◀──────────────── │   • Text extraction │
│   • Business logic  │   fill_url +       │   • Intelligent     │
│   • Your database   │   callback +       │     forms           │
│   • Your UI         │   structured data  │   • Encrypted       │
│                     │                    │     storage         │
│   Nothing changes   │                    │   • Automation        │
│   in your app.      │  Your backend      │     automation      │
│   Add one POST +    │  adds ~50 lines    │   • AI extraction   │
│   one callback.     │  of code.          │   • Doc preparation │
└─────────────────────┘                    └─────────────────────┘

The end user reaches the form through a one-time fill_url (or a direct
form link). They are NEVER logged in on the partner's behalf.

Your servers never handle text extraction, document storage, or form rendering.
Nocarta runs on its own infrastructure — your backend authenticates with its
own API key and receives structured data via HTTP callback.

---

Where It Fits in Your Application

Partner Integration is designed to be transparent to your existing system. Your application doesn't need to change its architecture, database schema, or user interface. You add one outbound redirect and one inbound callback handler — the rest of your system stays exactly as it is.

Your Application Has	Add Nocarta For
Customer onboarding	Automated document collection & identity verification — scan IDs, certificates, and licenses into structured fields
Invoice / expense automations	Instant text extraction with field capture — photograph a receipt, get vendor, date, amount, and line items back
Contract management	Digital form completion with typed fields, validation, and conditional logic — replace paper with structured data
Compliance & regulatory forms	Auditable data capture from paper documents with encryption, version history, and tamper-proof storage
Mobile field work	Photo-to-data capture for inspections, service logs, delivery receipts — works offline with the Desktop app
Customer portals	Self-service form submission with value set autocomplete, AI-powered fill, and real-time validation
Healthcare / insurance	Patient intake, claims submission, or policy forms with field-level encryption and privacy-compliant storage
Accounting & finance	Document preparation pipelines — split, merge, watermark, and extract data from invoices and statements in batch

Legacy Application Tip: If your app has an "upload document" button, a "complete this form" step, or any place where users deal with paper — that's exactly where Nocarta plugs in. Your existing UI stays the same. Users click a button in your app, complete the document task in Nocarta, and return to your app with structured data. To your users, it feels like a native feature of your product.

---

Benefits for Your Business

Benefit	What It Means
No infrastructure to build	Text extraction engines, document storage, encryption layers, form renderers, mobile capture, image alignment, AI extraction — all built and running. You don't hire for any of it.
Minutes, not months	The technical integration is about 50 lines of backend code. Adding new document types after that is configuration — no developer needed.
Transparent to your users	Partner-branded experience with your organization name, contact info, and identity. Users see your product, not ours.
Scale without changes	From 10 forms to 100,000 — same integration code, same callback handler, no infrastructure adjustments on your side.
Privacy law compliance	GDPR (EU), LGPD (Brazil), and major privacy regulation support built in. Data Processing Agreements available. Audit trails, consent tracking, right-to-deletion flows, and sub-processor documentation included. AES-256-GCM field-level encryption, scoped API keys, origin whitelisting, and violation logging protect every request.
Predictable cost	No separate text extraction API bills, no storage management fees, no surprise scaling charges. One integration, one relationship.

---

Integration Steps

Step	Who	Time
1. Create a Nocarta account	Manager	5 minutes
2. Build a form template from your paper document — upload a photo or let the AI generate it with Quick Document Capture	Manager	15–60 minutes
3. Enable Partner Mode on the template	Manager	2 minutes
4. Configure Partner Service settings: organization name, privacy policy URL, allowed origins, callback URL	Manager	10 minutes
5. Developer creates an API key in Settings → Profile and Connections, then adds the create-instance POST, the redirect to fill_url, and a callback handler to your app (code examples in Ruby, Node.js, Python)	Developer	15 minutes
6. End-to-end test: create an instance, open the fill_url, submit, confirm the callback	Both	10 minutes
7. Go live	Manager	Flip a switch

Adding a new document type after the initial setup requires zero code changes. The manager builds the template, enables partner mode, and it's available to your users immediately.

---

Start Even Faster: AI Integration (MCP)

Before writing any integration code, you can connect your application's AI layer to Nocarta through the AI Integration — a Model Context Protocol (MCP) endpoint that works with any AI assistant.

Connect your LLM — an internal chatbot, a customer-facing assistant, or an agent framework — to Nocarta's MCP endpoint, and it gains the ability to list templates, create form instances, scan documents, fill fields, search value sets, and work with notebooks. All through natural language.

This means you can offer AI-powered document processing to your users without writing a single line of integration code. Your AI assistant handles the orchestration; Nocarta handles the document intelligence.

Getting Started with MCP

1. Go to Settings → AI Integration and create an API token
2. Point your LLM at the MCP endpoint: https://app.nocarta.ai/mcp with Authorization: Bearer YOUR_TOKEN
3. Your AI can now orchestrate document automations on behalf of your users

Want to try it in 30 seconds? Click "Generate Setup Link" in AI Integration settings and paste the link into any AI chat (ChatGPT, Claude, Gemini). The assistant reads the link and auto-configures itself — no manual setup needed.

See AI Integration Guide for the full setup reference and usage limits.

---

Quick Start

1. Enable Partner Mode on your FormTemplate
2. Create an API key in Settings → Profile and Connections, scoped partner_instances:read / partner_instances:write
3. POST to /api/v1/partners/:id/instances with Authorization: Bearer <api_key> to create an instance and receive a one-time fill_url
4. Send the end user to fill_url — they fill the form without logging in

---

Authentication Flow

Your API Key (Bearer token)

All partner-to-Nocarta calls authenticate with your own API key, created in Settings → Profile and Connections and scoped to partner_instances:read and partner_instances:write. Pass it as a Bearer token:

Authorization: Bearer <api_key>

The API key authenticates your backend — it is not a user session and never logs anyone in. Keep it on your server; never expose it in a browser, a redirect URL, or client-side code.

Identifying the end user (B2B2C)

When the publisher's customers own their own instances (B2B2C mode), include the end user's email as subscriber_email in the create request body. The instance is created unaccepted (accepted: false); only that end user can accept it later and take ownership. In B2B mode you omit subscriber_email — the publisher owns the instance and it is created accepted.

---

Redirect-with-Reference (Flow B)

For the browser-redirect flow, your application sends the user straight to the form's short link with reference parameters. No token and no API key appear in the URL:

https://nocarta.ai/f/YOUR_SHORT_CODE?ref[key]=value&callback=https://you.example/cb&state=order_123

Parameter	Required	Description
ref[key]	No	Reference values read by fields configured with source ref (see Per-Field Prefill)
callback	No	URL the browser is redirected to after submission
state	No	Opaque string returned to your callback as partner_state

The end user fills the form anonymously, or signed in with their own Nocarta account — never with a partner-supplied session.

---

Error Codes

Partner API errors are plain JSON — an error label and a human-readable message. 422 responses carry the specific validation failures instead, in an errors array.

JSON Error Response Format

{
  "error": "Forbidden",
  "message": "Missing required scope: partner_instances:write"
}

For 422s:

{
  "errors": ["Valid subscriber_email required for B2B2C mode"]
}

Status Code Reference

Status	Cause	Resolution
401	API key missing or invalid	Send a valid Authorization: Bearer <api_key> header. Create or rotate the key in Settings → Profile and Connections.
403	API key lacks the required scope, or the template isn't within the key's resource_claims	Grant the key partner_instances:read and partner_instances:write in Profile and Connections settings, and confirm the template's UUID is included in (or unrestricted by) the key's resource claims.
404	The template id in the URL doesn't exist, isn't Partner Mode-enabled, or isn't published by your account	Verify the template id, that Partner Mode is on, and that you're using the publisher's API key. This endpoint never distinguishes "not found" from "not yours" — both return 404.
422	Missing/invalid subscriber_email in B2B2C mode, or a model validation failure	Check the errors array in the response for the specific failure.

---

Callback Response

After successful form submission, if a callback URL is configured, the user's browser is redirected with:

https://your-app.com/callback?nocarta_instance_id=UUID&status=submitted&partner_state=your_state

Parameter	Description
nocarta_instance_id	UUID of the created form instance
status	Always submitted on success
partner_state	Your original state parameter (if provided)

---

Integration Modes

B2B2C Mode (Default)

End users own their form instances and can sign into Nocarta with their own account. Include subscriber_email in the create request — it is required in this mode. Instances are created unaccepted (accepted: false); only the end user can accept and take ownership.

B2B Mode

Your organization (the publisher) owns all instances and posts them via its own API key, omitting subscriber_email. Instances are created accepted (accepted: true). End users access data only through your application.

---

End-User Access & Login

Filling a form through a one-time capability link never requires a login. Beyond that, whether — and when — the end user signs into Nocarta with their own credentials is governed by three template settings. The partner never logs in on the end user's behalf in any of these cases.

Setting	Values	Effect on end-user login
Integration mode partner_integration_mode	b2b2c (default) / b2b	b2b2c: the end user owns the instance and can have a Nocarta account. b2b: the publisher owns every instance; the end user has no Nocarta account or access and never logs in — they interact only through your app.
Relationship partner_enduser_nocarta_access (b2b2c only)	true = B2B2C (default) false = B2C	B2B2C: the end user reaches the form through your app (capability link); login is only needed for the actions below. B2C: the end user has a direct relationship with Nocarta and signs in with their own credentials to reach and manage their instances.
Read own data partner_enduser_can_read_instance (b2b2c only)	true (default) / false	true: the end user may sign in to Nocarta to view their submitted instance data (requires their own login). false: the end user cannot read their data in Nocarta; results flow back only to your app via callback/webhook.

Acceptance always requires the end user's own login

A partner-posted B2B2C instance is created accepted: false. It is attributed to the end user's account, but it is not theirs until they accept it — and only the end user, signed in with their own credentials, can accept (the partner cannot accept on their behalf). Acceptance stamps accepted_at and takes ownership. Filling the form via the capability link does not accept it; these are distinct steps.

Summary: no login to fill via a capability link; the end user's own login is required to accept an instance, to read their data in Nocarta (when enabled), and throughout in B2C. In B2B the end user never logs in at all.

---

API-Only Integration (Server-to-Server)

For server-to-server integrations where you don't need user redirection, Nocarta provides direct REST API endpoints. Your backend calls these endpoints directly — no browser, no redirect, no user interaction needed.

This is ideal for:

• Pushing structured data: Your system already has the field values — send them directly to create a filled form instance
• Batch processing: Create hundreds of instances programmatically from your own database
• Backend automation: Integrate document capture into pipelines, webhooks, or microservices
• Client-side integration: Call these endpoints from your own website or web client — no Nocarta UI needed

Available Endpoints

Endpoint	Method	Purpose
/api/v1/partners/:id/instances/fields	GET	Get your template's field map (UUIDs, names, types) for integration setup
/api/v1/partners/:id/instances	POST	Create an instance with field values

Authentication (All Endpoints)

All API endpoints authenticate with your own API key — the same key for every endpoint. Include it as a Bearer token in the Authorization header:

Authorization: Bearer <api_key>

Create the key in Settings → Profile and Connections with the partner_instances:read / partner_instances:write scopes (see Authentication Flow above). :id is your partner-enabled template's UUID, given as a URL path segment — not a request parameter.

---

1. Get Field Map

GET /api/v1/partners/YOUR_TEMPLATE_ID/instances/fields

Returns your template's fields with their UUIDs, names, and types. Use this to set up your integration — you'll need the field names or UUIDs when sending values.

Example Request (cURL)

curl https://nocarta.ai/api/v1/partners/YOUR_TEMPLATE_ID/instances/fields \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "template_id": "550e8400-...",
  "template_name": "Invoice Form",
  "fields": [
    {
      "id": "a1b2c3d4-...",
      "name": "customer_name",
      "cell_identifier": "A1",
      "type": "text",
      "required": false
    },
    {
      "id": "e5f6g7h8-...",
      "name": "invoice_date",
      "cell_identifier": "B2",
      "type": "date",
      "required": true
    }
  ]
}

---

2. Create Instance with Data

POST /api/v1/partners/:id/instances

Creates a form instance and fills it with the values you provide, where :id is your partner-enabled template's UUID. This is perfect when your system already has the data and you want to push it into a Nocarta form instance.

Request Body (JSON)

Parameter	Type	Required	Description
subscriber_email	String	B2B2C only	End user who will own the instance. Required in B2B2C mode; omit in B2B mode. Instance is created unaccepted until this user accepts it.
values	Object	No	Field values keyed by field name or UUID: { "customer_name": "Acme Corp" }
callback	String (URL)	No	URL to receive webhook when instance is closed
state	String	No	Opaque string returned in webhook callback (for your correlation)
name	String	No	Human-readable instance name
user_ref	String	No	Your own reference id for this end user, stamped onto the instance
partner_context	Object	No	Arbitrary context stamped onto the instance for your own bookkeeping

Example Request (cURL)

curl -X POST https://nocarta.ai/api/v1/partners/550e8400-.../instances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_email": "[email protected]",
    "values": {
      "customer_name": "Acme Corporation",
      "invoice_date": "2026-04-10",
      "total_amount": "1500.00"
    },
    "callback": "https://yourapp.com/webhook",
    "state": "order-12345"
  }'

# Response includes a one-time fill_url — send the end user there to fill the form.
# They are NOT logged in; in B2B2C the instance stays unaccepted until they accept it.

Example Request (Python)

import requests, os

# Create the key in Settings -> Profile and Connections; keep it server-side.
API_KEY = os.environ['NOCARTA_API_KEY']
TEMPLATE_ID = '550e8400-...'

response = requests.post(
    f'https://nocarta.ai/api/v1/partners/{TEMPLATE_ID}/instances',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'subscriber_email': '[email protected]',  # B2B2C only; omit for B2B
        'values': {
            'customer_name': 'Acme Corporation',
            'invoice_date': '2026-04-10',
            'total_amount': '1500.00'
        }
    }
)

result = response.json()
print(f"Instance ID: {result['instance_id']}")
print(f"Accepted: {result['accepted']}")
print(f"Send the user to: {result['fill_url']}")
print(f"Stored values: {result['values']}")

Example Request (JavaScript / Node.js)

// Create the key in Settings -> Profile and Connections; keep it server-side.
const apiKey = process.env.NOCARTA_API_KEY;
const templateId = '550e8400-...';

const response = await fetch(`https://nocarta.ai/api/v1/partners/${templateId}/instances`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscriber_email: '[email protected]', // B2B2C only; omit for B2B
    values: {
      customer_name: 'Acme Corporation',
      invoice_date: '2026-04-10',
      total_amount: '1500.00'
    }
  })
});

const result = await response.json();
console.log(`Instance ID: ${result.instance_id}`);
console.log(`Send the user to: ${result.fill_url}`);

Response (201 Created)

{
  "instance_id": "abc123-...",
  "status": "active",
  "accepted": false,
  "fill_url": "https://nocarta.ai/f/AbC123XyZ",
  "values": {
    "a1b2c3d4-...": "Acme Corporation",
    "e5f6g7h8-...": "2026-04-10",
    "i9j0k1l2-...": "1500.0"
  }
}

fill_url is a one-time capability link — send the end user there to fill the form without logging in. In B2B2C mode accepted is false until the end user accepts the instance; in B2B mode it is true. Values are keyed by field UUID in the response and sanitized per field type (numbers normalized, HTML stripped from text, dates converted to ISO 8601, invalid emails dropped).

---

Error Responses (All Endpoints)

Status	Cause
401	Missing or invalid API key
403	Missing required scope, or the template is outside the key's resource_claims
404	Template not found, not Partner Mode-enabled, or not published by your account
422	Missing/invalid subscriber_email in B2B2C mode, or a model validation failure

Use Case Examples

Data Push

Your CRM already has the customer's data. Push it into a Nocarta form instance for validation, digital signing, or archival:

1. Call GET /api/v1/partners/:id/instances/fields to map your CRM fields to Nocarta field names
2. Call POST /api/v1/partners/:id/instances with your data as values (plus subscriber_email for B2B2C)
3. Receive the instance ID and a one-time fill_url — the form is filled and ready
4. Optionally: send the end user to fill_url to review, sign, or accept the instance
5. When closed: webhook fires with the final values to your callback URL

Best Practices

• Use field names, not UUIDs: The values parameter accepts both, but field names are more readable and won't break if you recreate the template
• Protect your API key: Store it as a server-side secret (environment variable or secret manager). Never embed it in a browser, redirect URL, or client-side code. Rotate it in Settings → Profile and Connections if exposed
• Value types: All values are sanitized per field type — numbers are normalized, HTML is stripped, invalid emails are dropped. Check the response values to see what was actually stored
• Claim your token to one template: scope the key to partner_instances:read / partner_instances:write and restrict its resource_claims to this template's UUID, so a leaked key can't reach any other template

---

Partner Service Configuration

Before using Partner Integration, you must configure your Partner Service settings in Account Settings → Partner Service.

Profile Information

Your central profile data is displayed to end users when they interact with your partner integration:

Field	Where It Appears	Required
Name	Form headers, welcome messages	Recommended
Company	Emails, form branding	Recommended
Email	Support contact, notifications	Yes

Edit your profile in Account Settings → Profile

Organization Information

Organization details are shown in partner-generated emails and form interfaces:

Field	Purpose	Required
Organization Name	Displayed in emails: "Form from [Organization Name]"	Yes
Website URL	Linked in emails for user verification	Recommended
Contact Email	Reply-to address for partner emails	Yes (defaults to your email)

Compliance Requirements

For GDPR compliance when processing personal data, you must configure:

Privacy Policy

• Privacy Policy URL: Link to your privacy policy that covers Nocarta data processing
• Confirmation: Acknowledge that your privacy policy discloses Nocarta as a sub-processor

Your privacy policy should explain:

• That user data may be processed by Nocarta on your behalf
• What data is collected and how it's used
• User rights under GDPR (access, rectification, deletion)

UI Disclosure

You must inform users before redirecting them to Nocarta. Example disclosures:

• "Form processing powered by Nocarta"
• "Secure document processing via Nocarta"
• "You will be redirected to Nocarta to complete this form"

Data Processing Agreement (DPA)

A DPA is required if you process EU personal data through Partner Integration. The DPA establishes:

• You are the Data Controller (you determine purposes and means of processing)
• Nocarta is the Data Processor (we process data on your instructions)
• Security measures, data retention, sub-processor obligations

When is a DPA Required?

Scenario	DPA Required?
Processing EU citizen data (any location)	Yes
Processing any personal data in the EU	Yes
Processing only business data (no PII)	No
Using B2B mode with no end-user PII	No

How to Get a DPA

1. Contact [email protected] to request a DPA
2. Review and sign the agreement
3. Mark "DPA Signed" in your Partner Service settings
4. Provide signatory details for our records

Legal & Privacy Status

The Partner Service page displays your acceptance status for:

• Terms of Service: Your agreement with Nocarta
• Privacy Policy: Nocarta's data handling practices

These are separate from the compliance requirements above, which govern how you handle your end-users' data.

---

Per-Field Prefill

Prefill is configured per field on the template, in the Partner Integration panel → per-field editor. Each field declares where its initial value comes from and how it's treated — there is no global prefill blob and no field whitelist; a field is prefillable exactly when it has a source configured.

Per-Field Settings

Setting	Description
source	Where the value comes from: ref (a URL reference parameter, ref[key]), api (a value from the partner API request payload), or static (the configured default)
ref_key	For source: ref, the key to read from the ref[...] URL parameters
default	Fallback value used when the chosen source yields nothing (and the literal value for source: static)
format	Normalization applied to the value (see formats below)
locked	When true, the field is read-only to the end user and the prefilled value is authoritative on submit
required	When true, the field must have a value or submission is blocked

Available Formats

Each field's format normalizes the incoming value before it's stored or displayed:

Format	Effect
none	No change
trim	Strip leading/trailing whitespace
uppercase	Convert to upper case
lowercase	Convert to lower case
titlecase	Capitalize each word
digits_only	Keep digits only
cpf_mask	Format as a Brazilian CPF
cnpj_mask	Format as a Brazilian CNPJ
phone_br	Format as a Brazilian phone number
date_iso	Normalize to ISO 8601 date
currency_2dp	Currency with two decimal places

How Sources Resolve

• ref: reads ref[ref_key] from the form link (Flow B). If absent, falls back to default
• api: reads the matching value from the partner API values payload (the create-instance POST). If absent, falls back to default
• static: always uses default
• locked fields stay read-only to the end user and win on submit; required fields block submission until filled

---

Testing

To test without touching production data, use a draft (unpublished is fine for API checks) or a dedicated test template, and a throwaway subscriber_email. Create an instance with your API key, open the returned fill_url, submit, and confirm your callback fires. Delete the test instances afterward.

---

Troubleshooting

API Key Issues

• 401 Unauthorized: Confirm the Authorization: Bearer <api_key> header is present and the key is active
• 403 Forbidden scope: Grant the key partner_instances:read and partner_instances:write in Settings → Profile and Connections, and confirm the template's UUID is covered by the key's resource claims (or that they're unrestricted)
• Compromised key: Rotate it in Profile and Connections settings; the old key stops working immediately

Origin Issues

• Add your application's domain to Partner Allowed Origins
• Include protocol: https://app.example.com
• Direct access (no referrer) is always allowed

Prefill Issues

• Configure the field's source (ref, api, or static) in the template's per-field editor — a field with no source is not prefillable
• For source: ref, the ref_key must match the ref[key] name in the form link
• For source: api, the key in your values payload must match the field name or UUID
• Check the violations log for details on rejected prefills

---

Code Examples

Each example creates the instance from your backend with your API key, then sends the end user to the returned fill_url. The API key is created once in Settings → Profile and Connections and kept server-side — never put it in the browser.

Ruby

require 'net/http'
require 'json'

api_key = ENV.fetch('NOCARTA_API_KEY') # from Settings -> Profile and Connections

uri = URI("https://nocarta.ai/api/v1/partners/#{template_id}/instances")
req = Net::HTTP::Post.new(uri, {
  'Authorization' => "Bearer #{api_key}",
  'Content-Type'  => 'application/json'
})
req.body = {
  subscriber_email: user.email, # B2B2C only; omit for B2B
  values: { 'customer_name' => 'Acme Corporation' }
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
result = JSON.parse(res.body)

# Send the end user to the one-time fill link (they are NOT logged in)
redirect_url = result['fill_url']

JavaScript (Node.js)

// Keep the key server-side — from Settings -> Profile and Connections
const apiKey = process.env.NOCARTA_API_KEY;

const res = await fetch(`https://nocarta.ai/api/v1/partners/${templateId}/instances`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscriber_email: user.email, // B2B2C only; omit for B2B
    values: { customer_name: 'Acme Corporation' }
  })
});

const result = await res.json();
// Send the end user to the one-time fill link (they are NOT logged in)
const redirectUrl = result.fill_url;

Python

import os, requests

api_key = os.environ['NOCARTA_API_KEY']  # from Settings -> Profile and Connections

res = requests.post(
    f'https://nocarta.ai/api/v1/partners/{template_id}/instances',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'subscriber_email': user.email,  # B2B2C only; omit for B2B
        'values': {'customer_name': 'Acme Corporation'}
    }
)

result = res.json()
# Send the end user to the one-time fill link (they are NOT logged in)
redirect_url = result['fill_url']

For the browser-redirect flow (Flow B) there is no backend call — your app simply redirects to https://nocarta.ai/f/SHORT_CODE?ref[key]=value&callback=…&state=…. See Per-Field Prefill for how ref[...] values map to fields.

---

Need Help?

• AI Assistant: Ask integration questions in natural language
• Support Ticket: Create a ticket for complex issues
• Violations Log: Check your template's partner violations for debugging info

---

Related Features

• Translation API: Programmatic diagram-to-config conversion. Submit diagrams via API and receive Nocarta objects (automations, form templates, etc.) as structured JSON.
• Security — API Keys: Create API keys for programmatic access to Partner and Translation APIs.