Generate a company API key inside Ultrasys ERP.
Integration model
Your backend is the bridge between the field app and the ERP.
External field systems should keep Ultrasys credentials on their server side. Mobile users authenticate with the field application, while that backend calls Ultrasys ERP with a company-scoped API key. The key limits access by company, active subscription, expiry, and scope.
Store the key securely on your backend, never in a mobile app.
Sync customers first and keep the returned Ultrasys customer ID.
Create sales orders against the synced customer ID.
Read the aging report for debtor balances and rep-specific collections.
Endpoints
Operations exposed for field management workflows.
POSTcustomers:create
Create or match a customer
/api/developer/external/customersCreates a customer for the API key company, or returns a matched existing customer when the customer name and sales rep already align.
PATCHcustomers:create
Repair customer rep assignment
/api/developer/external/customers/{customerId}/assignmentUpdates the sales representative for an existing synced customer using rep ID, email, or name.
POSTsales:create
Create a sales order
/api/developer/external/sales-ordersCreates a pending Ultrasys ERP sales order, resolves mapped items, checks customer credit limits, and writes the customer ledger entry.
PATCHsales:create
Repair sales order lines
/api/developer/external/sales-orders/{orderId}/itemsReplaces item lines on a pending order when product mapping becomes available after the first sync.
GETreports:aging
Read debtor aging
/api/developer/external/aging-reportReturns outstanding invoices by customer, with optional sales rep filtering for mobile debt collection views.
Send the API key in `x-api-key`.
API keys are generated by an Ultrasys ERP administrator and shown once. Send the raw key value in the `x-api-key` header. The scheme is intentionally empty, so do not add `Bearer` or another prefix.
ERP_BOOTSTRAP_COMPANY_ID=your_client_company_id ERP_TOKEN_ENCRYPTION_KEY=replace-with-at-least-32-random-characters ERP_ULTRASYS_API_KEY_HEADER=x-api-key ERP_ULTRASYS_API_KEY_SCHEME=
Set `ERP_BOOTSTRAP_COMPANY_ID` to the client company ID used by the field management application. Keep `ERP_TOKEN_ENCRYPTION_KEY` secret and unchanged; it must contain at least 32 random characters and protects stored ERP credentials.
Each key can be limited to customer creation, sales creation, aging reports, and an optional expiry period.
customers:createsales:createreports:aging
Keep the returned ERP IDs.
Save `customer.id` after customer sync and `sales_order.id` after order sync. Product and sales rep mappings can use Ultrasys numeric IDs, or rep email/name when the ERP can resolve them.
customer.idsales_order.idrep_filter_appliedExamples
Payloads used by a FieldMatters-style integration.
Customer sync
POST https://api.ultrasyserp.com/api/developer/external/customers
x-api-key: cdt_your_generated_key
Content-Type: application/json
{
"customer_code": "FM-A33F42",
"customer_name": "Alpha Stores",
"customer_type": "BUSINESS",
"email": "[email protected]",
"phone": "08030000000",
"address": "Lagos",
"credit_limit": 250000,
"payment_terms": "NET_30",
"sales_rep_email": "[email protected]",
"sales_rep_name": "Test Rep",
"price_list_id": 4,
"is_active": true
}Sales order sync
POST https://api.ultrasyserp.com/api/developer/external/sales-orders
x-api-key: cdt_your_generated_key
Content-Type: application/json
{
"customer_id": 42,
"order_date": "2026-09-25",
"sales_rep_email": "[email protected]",
"payment_terms": "NET_30",
"remarks": "Field app order SO-10018",
"order_items": [
{
"item_id": 11,
"item_name": "Widget",
"quantity": 2,
"unit_price": 50,
"discount_percent": 0
}
]
}Debtor aging lookup
GET https://api.ultrasyserp.com/api/developer/external/aging-report?as_of_date=2026-09-25&[email protected] x-api-key: cdt_your_generated_key