Signicat Mint API - European Identity Verification That Actually Works

Here's the deal: Signicat Mint isn't just another e-signature API. I've been using it for 8 months now, and honestly? It solves a problem I didn't know I had until I tried integrating Norwegian BankID directly. Your business users drag and drop components to build identity verification flows, then you trigger those flows from your code instead of redirecting to their hosted pages. Think Zapier for identity verification, but with actual European regulatory compliance.

The Business User Problem It Solves

Every company needs identity verification workflows. Traditional approaches suck because either:

1. Developers build everything from scratch (slow, expensive, compliance nightmare)
2. Business users are stuck with whatever the developers built (inflexible, constant change requests)

Mint Builder fixes this by letting non-technical users create the workflows visually. Seriously - they drag boxes around like a flowchart and connect them. When they want changes, they edit it themselves instead of filing tickets.

But here's where it gets useful for developers: the Mint API lets you trigger these workflows programmatically:

## Start a workflow from your code
POST /flows/{id}/execute
Authorization: Bearer {token}
{
  "input": {
    "email": "user@example.com",
    "product": "premium_account"
  }
}

You get back an instance ID, monitor the status, download the results when it's finished. No more "please fill out this form on our partner's website" bullshit.

European Identity Integration (The Real Reason You'd Use This)

The killer feature is European eID support. Signicat connects to 35+ national identity systems - BankID in Norway and Sweden, MitID in Denmark, itsme in Belgium, plus all the eIDAS nodes.

If you're operating in Europe and need strong identity verification, your alternatives are basically:

• Build custom integrations with each country (months of work, ongoing maintenance nightmare)
• Use a global provider that supports maybe 3-4 European methods (good luck with compliance)
• Partner with local providers in each market (integration hell)

Or just use Mint and get access to all of them through one API. I've spent weeks trying to integrate Norwegian BankID directly - their documentation is in Norwegian and the error messages make zero sense. Mint handles all that complexity.

MintyAI: Actually Useful AI Integration

MintyAI lets business users describe workflows in plain English and get working flow diagrams. I was skeptical but tried it with "verify user identity, sign employment contract, create DocuSign backup" and got a reasonable workflow structure in 30 seconds.

The AI explains what each component does and suggests compliance requirements based on the workflow type. Not revolutionary, but actually saves time compared to clicking through their component library. Plus business users can experiment without breaking production workflows.

When You'd Actually Choose This

You'd pick Mint API when:

• European operations - You need BankID, MitID, or other European eID methods
• Complex workflows - Beyond simple document signing into multi-step identity verification
• Business user autonomy - You want to avoid being the bottleneck for workflow changes
• Compliance requirements - Financial services, healthcare, or other regulated industries

You wouldn't choose it for:

• Simple e-signatures - DocuSign is cheaper and more straightforward
• US-only operations - Limited value outside Europe
• Developer-controlled workflows - If you want full programmatic control, build it yourself
• Cost sensitivity - Enterprise pricing model, not suitable for small projects

The eIDAS 2 regulations coming in 2026 will make European digital identity even more complex. Mint positions you to handle those changes without rebuilding your identity stack.

OAuth 2.0 Setup: Not As Simple As They Make It Sound

The auth setup uses standard OAuth 2.0 client credentials, but there are gotchas:

The Setup Process (Takes 10 minutes, not 2):

1. Create API client in Signicat Dashboard - obvious step
2. Choose "Flow Editor" or "Flow Viewer" role - Flow Viewer can't execute workflows, learned this the hard way
3. Domain verification required - they need to verify you own the domain, adds 24-48 hours
4. Get client ID and secret - store these securely, they don't show the secret again

Auth Implementation That Actually Works:

// Don't use the example in their docs - it's missing error handling
// Based on OAuth 2.0 Client Credentials spec: https://tools.ietf.org/html/rfc6749#section-4.4
async function getAccessToken() {
  const response = await fetch('https://api.signicat.com/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.SIGNICAT_CLIENT_ID,
      client_secret: process.env.SIGNICAT_CLIENT_SECRET
    })
  });
  
  if (!response.ok) {
    throw new Error(`Auth failed: ${response.status} ${response.statusText}`);
  }
  
  const { access_token, expires_in } = await response.json();
  return { token: access_token, expiresIn: expires_in };
}

Auth Failures That Will Ruin Your Day:

• invalid_client = wrong client ID/secret (check for trailing spaces)
• unauthorized_client = domain not verified yet (check your dashboard settings)
• access_denied = wrong role permissions (need Flow Editor, not Flow Viewer)
• Token expires in 3600 seconds - implement refresh or you'll get 401s randomly

API Endpoints: The Good and The Annoying

Starting a Workflow (Usually Works):

curl -X POST 'https://api.signicat.com/flows/abc123/execute' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"email": "user@company.com"}}'

Response includes instanceId - save this immediately, you'll need it for everything else.

Monitoring Status (Polling Required):

## Check if it's finished
curl "https://api.signicat.com/flows/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN"

Status values you'll actually see:

• Running - workflow is processing
• Suspended - waiting for user input (common with identity verification)
• Finished - completed successfully
• Faulted - something broke (check the error details)
• Cancelled - user abandoned it

The Suspended Workflow Pain:
Workflows suspend when they need user interaction (like BankID authentication). You can't do anything except wait. The API doesn't tell you what specific step it's waiting for - you have to infer from the workflow design.

File Downloads: Works But Has Quirks

// Download completed documents
const downloadUrl = `https://api.signicat.com/flows/instances/${instanceId}/files/${referenceId}/download`;
const response = await fetch(downloadUrl, {
  headers: { 'Authorization': `Bearer ${token}` }
});

// Response is the actual file, not JSON
const buffer = await response.buffer();
fs.writeFileSync('signed_document.pdf', buffer);

Download gotchas:

• Files expire after 30 days (not documented clearly)
• Large files (>10MB) sometimes timeout - implement retry logic
• ZIP files for multi-document workflows come back as single download
• No progress tracking for large downloads

Error Handling: What You'll Actually Encounter

Common API errors that aren't in the docs:

HTTP 429 - Rate Limited:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}

No documented rate limits, but you'll hit them around 100 req/min during testing.

HTTP 422 - Workflow Validation:

{
  "error": "workflow_validation_failed", 
  "details": "Required input parameter 'phoneNumber' missing"
}

Happens when your input doesn't match what the workflow expects. The business users designing workflows often forget to mark fields as optional.

HTTP 503 - Service Unavailable:

{
  "error": "service_temporarily_unavailable"
}

Usually means European identity providers are down (BankID maintenance, etc.). Implement exponential backoff and user messaging.

Performance: The Good, The Bad, and The 'Why Is This So Slow'

Response Times (From EU servers):

• Flow execution is usually under 500ms to get your instance ID
• Status checks are pretty fast, maybe 100-200ms
• File downloads take forever - 2-10 seconds for normal PDFs, longer if something goes wrong
• European eID verification: 5-30 seconds depending on the provider

Reliability Issues I've Seen:

• Swedish BankID goes down every few months for maintenance
• Danish MitID has weekend outages sometimes
• File generation can take 2-3 minutes for complex workflows
• API responses occasionally return 502 during European business hours (load issues)

Scaling Considerations:
They claim 1 billion transactions annually, but that's across their entire platform. For the API specifically:

• Batch operations aren't supported - you're polling one workflow at a time
• No webhooks - you have to poll for status updates like it's 2005
• Instance monitoring gets slow with 100+ concurrent workflows

Integration Patterns That Work

CRM Trigger Pattern:

// When a lead converts, start identity verification
async function onLeadConversion(leadId, contactInfo) {
  const instance = await executeWorkflow('identity-verification-flow', {
    email: contactInfo.email,
    phone: contactInfo.phone,
    crmLeadId: leadId
  });
  
  // Store instance ID for later polling
  await db.updateLead(leadId, { 
    verificationInstanceId: instance.id,
    status: 'verification_started'
  });
}

Background Job Pattern:

// Poll for completed workflows every 30 seconds
async function pollWorkflowStatus() {
  const pending = await db.getPendingVerifications();
  
  for (const record of pending) {
    const status = await getWorkflowStatus(record.instanceId);
    
    if (status === 'Finished') {
      const documents = await downloadWorkflowFiles(record.instanceId);
      await processCompletedVerification(record.crmLeadId, documents);
    }
  }
}

What The Documentation Doesn't Tell You

Testing Gotchas:

• Sandbox and production have separate accounts - workflows don't transfer
• Some European eID methods don't work in sandbox (BankID, MitID)
• Test user accounts exist but aren't documented well
• File downloads in sandbox return dummy PDFs

Production Deployment:

• European data residency is real - latency from US East Coast is 150-200ms
• Domain verification takes 1-2 business days, plan accordingly
• Support responds in European business hours (CET timezone)
• Pricing is negotiated per-customer, expect enterprise sales process

The platform works well for European identity verification, but expect to spend time dealing with the quirks of each national eID system. Their API abstracts most of the complexity, but not all of it.