Customer Mapping | Ordinavo Connect API

Link imported jobs to customers, locations and contacts in Ordinavo

Ordinavo Connect can receive customer, location and contact data together with incoming jobs. Ordinavo can map these records by external IDs, customer numbers or controlled mapping settings and attach the resulting customer context to the imported target.

Once mapped, the customer context stays available in scheduling, Smart Routing AI, MyDay, visit reports, customer timeline and outbound webhooks.

Inbound requestcustomer.externalIdCustomerExternalReference lookupCustomer / Location / Contact mappingTarget.CustomerIdScheduling / Routing / MyDay / Visit Reports / Webhooks

Tenant-safe references

External IDs are scoped by tenant, source system and external type. The same external ID can exist in different tenants without leaking data.

Matching strategies

Strategy	Behavior
`ExternalIdOnly`	Only maps by external IDs already known to Ordinavo.
`ExternalIdFirst`	Recommended default. Uses external IDs first and falls back only to configured safe matching.
`ExternalIdThenCustomerNumber`	Uses external IDs first, then a unique customer number inside the same tenant.
`ExternalIdThenNameAndAddress`	Uses external IDs first and may identify candidates by strong name and address signals.
`ManualOnly`	Does not auto-link customer records. Items can be reviewed manually.

Name matching warning

Name-based matching can be ambiguous. Ordinavo marks ambiguous results as warnings instead of silently linking to the wrong customer.

Required scopes

Scope	Purpose
`customers.map`	Allows Ordinavo to map imported records to existing customer references.
`customers.write`	Allows Ordinavo to create or update customers, locations and contacts during import.
`customers.read`	Allows API responses to include detailed mapping IDs and customer mapping results.

targets.write or inbound.targets.write is required to import targets. Customer mapping scopes are additional permissions for attaching customer context.

Customer DTO

{
  "customer": {
    "externalId": "CUST-10042",
    "customerNumber": "RRM-001",
    "name": "Rhein-Ruhr Medical Supply",
    "type": "Business",
    "industry": "Medical Supply",
    "email": "operations@example.com",
    "phone": "+49 201 123456",
    "website": "https://example.com"
  }
}

customer.externalId is the preferred stable reference from the external system. customer.customerNumber is stored on the Ordinavo customer record and never on the target.

Location DTO

{
  "location": {
    "externalId": "LOC-ESSEN-01",
    "name": "Essen Center",
    "type": "Branch",
    "street": "Hachestrasse 12",
    "postalCode": "45127",
    "city": "Essen",
    "region": "North Rhine-Westphalia",
    "country": "DE",
    "latitude": 51.451,
    "longitude": 7.012,
    "defaultEstimatedWorkMinutes": 45,
    "defaultPriority": "High",
    "accessNotes": "Use the staff entrance near the loading area.",
    "parkingNotes": "Parking available behind the building."
  }
}

Location defaults can be reused for imported targets, recurring visits and route planning. Coordinates improve Smart Routing AI and route readiness.

Contact DTO

{
  "contact": {
    "externalId": "CONT-44",
    "firstName": "Anna",
    "lastName": "Weber",
    "displayName": "Anna Weber",
    "role": "Operations Manager",
    "department": "Store Operations",
    "email": "anna.weber@example.com",
    "phone": "+49 201 123456",
    "mobile": "+49 170 1234567",
    "preferredContactMethod": "Phone"
  }
}

Mapped contacts are shown to dispatchers and mobile employees where operationally relevant.

Mapping status

Status	Meaning
`NotApplicable`	No customer mapping payload was provided.
`Mapped`	Existing customer, location or contact was mapped.
`Created`	A new customer, location or contact was created.
`Updated`	Existing mapped data was updated.
`Warning`	Mapping succeeded with warnings.
`Failed`	Mapping failed and the import item needs review.
`Skipped`	Mapping was disabled or not allowed by policy.

Mapping warnings

LocationMissingCoordinates AmbiguousCustomerNumber TargetAddressDiffersFromCustomerLocation CustomerAutoCreateDisabled LocationAutoCreateDisabled ContactAutoCreateDisabled ContactLocationMismatch CustomerArchivedOrBlocked

{
  "customerMapping": {
    "status": "Warning",
    "customerId": 12,
    "customerLocationId": 34,
    "customerContactId": null,
    "warnings": [
      "LocationMissingCoordinates",
      "ContactAutoCreateDisabled"
    ]
  }
}

Security and privacy notes

Do not send unnecessary personal data.
Use stable external IDs instead of free-text matching.
Webhook consumers should store only the data they need.
Contact details can be disabled in webhook payload options.
Summary previews are disabled by default.
Billing details require explicit feature and subscription configuration.