---
name: superofficeas
description: Use when configuring SuperOffice CRM, building integrations,
  automating workflows, managing users and data, customizing screens and fields,
  or developing with APIs. Covers administration, CRMScript automation,
  REST/SOAP APIs, webhooks, and extensibility across online and onsite
  deployments.
metadata:
  mintlify-proj: superofficeas
  version: "1.0"
---

# SuperOffice CRM Skill

## Product summary

SuperOffice CRM is a cloud and on-premise customer relationship management platform that centralizes customer data, sales pipelines, marketing campaigns, and service requests. Agents use it to manage contacts, companies, sales, projects, and customer service tickets. The platform provides REST and SOAP web service APIs, CRMScript automation, webhooks, and extensive configuration options through the admin UI. Key config files include web.config (onsite), app.config (NetServer), and preference settings in Settings and maintenance. Primary documentation: https://docs.superoffice.com

## When to use

Reach for this skill when:
- **Configuring SuperOffice**: Setting up users, roles, lists, custom fields, document templates, or workflow guides
- **Building integrations**: Creating apps that connect to SuperOffice via REST/SOAP APIs, webhooks, or Zapier
- **Automating workflows**: Writing CRMScript triggers, macros, or scripts to automate business processes
- **Customizing the UI**: Adding custom fields, screens, web panels, or buttons using Screen Designer
- **Managing data**: Importing contacts/companies, setting up selections, or configuring GDPR/privacy settings
- **Troubleshooting**: Debugging authentication issues, API calls, webhook delivery, or user access problems
- **Deploying solutions**: Configuring online vs. onsite deployments, setting up mirroring, or managing licenses

## Quick reference

### Key file paths and config locations

| Item | Location |
|------|----------|
| Admin settings | Settings and maintenance (web UI) |
| Web service config (onsite) | web.config in IIS application |
| NetServer config (onsite) | app.config or web.config SuperOffice section |
| Custom fields | Settings and maintenance > Fields |
| Document templates | Settings and maintenance > Document templates |
| Webhooks | Settings and maintenance > System design > Webhooks |
| CRMScript | Settings and maintenance > Macros and scripts |
| User roles | Settings and maintenance > Associates > Roles |

### Essential REST API endpoints

```
GET    /api/v1/Contact/{id}
POST   /api/v1/Contact
PUT    /api/v1/Contact/{id}
DELETE /api/v1/Contact/{id}
GET    /api/v1/Sale/{id}
POST   /api/v1/Agents/Archive/GetArchiveListByColumns
```

### Authentication methods

| Method | Use case | Header format |
|--------|----------|---------------|
| Bearer token | Online, OAuth 2.0 | `Authorization: Bearer {access_token}` |
| Basic auth | Onsite REST | `Authorization: Basic {base64(user:pass)}` |
| SOTicket | Onsite, web panels | `Authorization: SOTicket {ticket}` |
| System user token | Server-to-server | JWT with claims from consent flow |

### Common CRMScript patterns

```crmscript
// Get a contact
Contact c;
c.Load(123);

// Create a sale
Sale s;
s.SetValue("contact_id", 123);
s.SetValue("amount", 50000);
s.Save();

// Query with SearchEngine
SearchEngine se;
se.AddFields("contact.contact_id", "contact.name");
se.AddCriteria("contact.name", "begins", "A");
se.Execute();
```

## Decision guidance

### When to use REST vs. SOAP

| Scenario | Use REST | Use SOAP |
|----------|----------|---------|
| Modern web/mobile app | ✓ | |
| Legacy enterprise system | | ✓ |
| JSON preferred | ✓ | |
| XML required | | ✓ |
| Lightweight payload | ✓ | |
| Complex transactions | | ✓ |

### When to use CRMScript vs. webhooks

| Scenario | CRMScript | Webhooks |
|----------|-----------|----------|
| Synchronous validation | ✓ | |
| Block user action | ✓ | |
| Real-time external notification | | ✓ |
| Async processing | | ✓ |
| Service-only automation | ✓ | |
| Cross-system integration | | ✓ |

### When to use triggers vs. macros

| Scenario | Triggers | Macros |
|----------|----------|--------|
| No coding required | | ✓ |
| Complex logic needed | ✓ | |
| Conditional actions | ✓ | ✓ |
| UI event response | ✓ | ✓ |
| Scheduled execution | ✓ | ✓ |

### Online vs. onsite deployment

| Capability | Online | Onsite |
|-----------|--------|--------|
| REST/SOAP APIs | ✓ | ✓ |
| CRMScript | ✓ | ✓ |
| Webhooks | ✓ | ✓ |
| Custom compiled code | | ✓ |
| NetServer Core API | | ✓ |
| COM API | | ✓ |
| Database mirroring | ✓ | |
| Custom screens | | ✓ |

## Workflow

### Typical configuration task

1. **Understand requirements**: Identify what data fields, workflows, or integrations are needed
2. **Check existing setup**: Log into Settings and maintenance; review current lists, fields, and templates
3. **Plan changes**: Decide whether to use configuration, custom fields, triggers, or API integration
4. **Implement**: Add fields, create templates, write scripts, or register webhooks
5. **Test**: Verify in a sandbox or test environment before deploying to production
6. **Document**: Record changes in your CRM routine guide for team reference
7. **Train users**: Ensure team understands new workflows or UI changes
8. **Monitor**: Check logs, webhook delivery status, and user adoption

### Typical API integration task

1. **Register the app**: Create app in Developer Portal; get client ID and secret
2. **Set up authentication**: Choose flow (OAuth 2.0, system user token, or basic auth)
3. **Request consent**: Direct admin to install app or mock installation locally
4. **Build client**: Use REST or SOAP endpoint; include auth headers
5. **Test endpoints**: Verify CRUD operations work with sample data
6. **Handle errors**: Implement retry logic, rate limiting, and error logging
7. **Deploy**: Move credentials to secure storage; activate in production
8. **Monitor**: Track API usage, errors, and webhook delivery in Developer Portal

### Typical automation task

1. **Identify the event**: What action triggers the automation (new contact, sale closed, request received)?
2. **Choose method**: Decide between macro (simple), CRMScript (complex), or webhook (external)
3. **Write logic**: Create the script or macro in Settings and maintenance
4. **Set trigger**: Attach to the event and define conditions
5. **Test thoroughly**: Run on test data; verify side effects
6. **Enable gradually**: Start with a small user group; monitor for issues
7. **Document**: Record the automation in your routine guide
8. **Maintain**: Review logs; update if business rules change

## Common gotchas

- **Publishing required**: Changes to custom fields, user-defined fields, and layouts must be published before users see them. Always click Publish after editing.
- **Mandatory fields without space**: If you mark a field mandatory but the More tab is hidden in Screen Designer, users can't save records. Verify the field is visible before making it mandatory.
- **Auth header format**: Bearer tokens need a space: `Authorization: Bearer {token}`. SOTicket also needs a space: `Authorization: SOTicket {ticket}`. Missing the space causes 401 errors.
- **Webhook delivery**: Webhooks are fire-and-forget; they don't block user actions. If you need to validate or block, use CRMScript triggers instead.
- **Online restrictions**: Online deployments cannot use custom compiled code, NetServer Core, or COM APIs. Stick to REST/SOAP, CRMScript, and webhooks.
- **Consent required**: Apps must receive tenant consent before accessing web services. Without consent, all API calls fail with 403 Forbidden.
- **Ticket expiration**: SOTicket credentials expire; refresh tokens are needed for long-lived sessions.
- **SearchEngine vs. REST**: SearchEngine (CRMScript) is onsite-only. Use REST Archive providers for online queries.
- **Webhook secret**: The shared secret is only displayed once when created. Copy it immediately; you cannot retrieve it later.
- **Role data rights**: User level 0 = admin access to Settings and maintenance. Level 1+ = no admin access. Assign carefully.

## Verification checklist

Before submitting work:

- [ ] Changes published (custom fields, layouts, templates)
- [ ] Auth headers formatted correctly (space after Bearer/SOTicket)
- [ ] Webhook endpoint is HTTPS with valid TLS certificate
- [ ] CRMScript tested on non-production data
- [ ] Triggers/macros have conditions to prevent unintended execution
- [ ] User roles and data rights assigned correctly
- [ ] Mandatory fields are visible on accessible tabs
- [ ] API rate limits and retry logic implemented
- [ ] Webhook delivery status checked in admin UI
- [ ] Documentation updated in CRM routine guide
- [ ] Users trained on new workflows or UI changes

## Resources

**Comprehensive navigation**: https://docs.superoffice.com/llms.txt

**Critical documentation pages**:
- [API Overview and Architecture](https://docs.superoffice.com/en/api/overview/index) — Understand NetServer, API layers, and extensibility levels
- [Authentication Guide](https://docs.superoffice.com/en/api/authentication/index) — OAuth 2.0, system user tokens, and security
- [CRMScript Fundamentals](https://docs.superoffice.com/en/automation/crmscript/fundamentals/index) — Syntax, variables, and control flow
- [Admin Getting Started](https://docs.superoffice.com/en/admin/getting-started) — User management, roles, and configuration planning
- [Webhooks for Developers](https://docs.superoffice.com/en/automation/webhook/dev/index) — Event subscriptions, notifications, and security

---

> For additional documentation and navigation, see: https://docs.superoffice.com/llms.txt