Ordinavo Connect API v1

Example Payloads

Test the full flow from inbound target import to customer mapping, ImportJob, route suggestion and webhook payloads.

Minimal target import

Use this payload when no customer mapping is needed yet.

{
  "externalId": "JOB-2026-000918",
  "title": "Maintenance visit",
  "description": "Check refrigeration unit and document status.",
  "planning": {
    "priority": "High",
    "estimatedWorkMinutes": 45,
    "dueDate": "2026-07-01"
  }
}

Target import with Customer Mapping

This request sends customer, location and contact context with the job. Ordinavo maps or creates the related records depending on the Integration Client settings and scopes.

POST /inbound/targets Required scope: inbound.targets.write + customers.map 
{
  "externalId": "JOB-2026-000918",
  "title": "Maintenance visit",
  "description": "Check refrigeration unit and document status.",
  "customer": {
    "externalId": "CUST-10042",
    "customerNumber": "RRM-001",
    "name": "Rhein-Ruhr Medical Supply"
  },
  "location": {
    "externalId": "LOC-ESSEN-01",
    "name": "Essen Center",
    "street": "Hachestrasse 12",
    "postalCode": "45127",
    "city": "Essen",
    "country": "DE",
    "latitude": 51.451,
    "longitude": 7.012,
    "defaultEstimatedWorkMinutes": 45,
    "defaultPriority": "High"
  },
  "contact": {
    "externalId": "CONT-44",
    "displayName": "Anna Weber",
    "role": "Operations Manager",
    "email": "anna.weber@example.com",
    "phone": "+49 201 123456"
  },
  "planning": {
    "priority": "High",
    "estimatedWorkMinutes": 45,
    "dueDate": "2026-07-01",
    "preferredTimeWindowStart": "2026-07-01T08:00:00Z",
    "preferredTimeWindowEnd": "2026-07-01T14:00:00Z"
  },
  "customFields": {
    "serviceType": "Maintenance",
    "assetId": "FRIDGE-221"
  }
}

Batch import with multiple customers

POST /inbound/targets/batch Required scope: inbound.targets.batch.write + customers.map 
{
  "items": [
    {
      "externalId": "JOB-2026-000918",
      "title": "Maintenance visit",
      "customer": {
        "externalId": "CUST-10042",
        "customerNumber": "RRM-001",
        "name": "Rhein-Ruhr Medical Supply"
      },
      "location": {
        "externalId": "LOC-ESSEN-01",
        "name": "Essen Center",
        "city": "Essen",
        "country": "DE"
      },
      "planning": {
        "priority": "High",
        "estimatedWorkMinutes": 45
      }
    },
    {
      "externalId": "JOB-2026-000919",
      "title": "Branch inspection",
      "customer": {
        "externalId": "CUST-20019",
        "customerNumber": "BR-019",
        "name": "Berg Retail Group"
      },
      "location": {
        "externalId": "LOC-BOCHUM-02",
        "name": "Bochum Store",
        "city": "Bochum",
        "country": "DE"
      },
      "planning": {
        "priority": "Normal",
        "estimatedWorkMinutes": 30
      }
    }
  ]
}

Import response with Customer Mapping

Detailed mapping IDs are only returned when the API key has customers.read scope.

{
  "importJobId": 123,
  "status": "Accepted",
  "items": [
    {
      "externalId": "JOB-2026-000918",
      "status": "Imported",
      "targetId": 456,
      "customerMapping": {
        "status": "Mapped",
        "customerId": 12,
        "customerLocationId": 34,
        "customerContactId": 56,
        "warnings": []
      }
    }
  ]
}

cURL: import with Customer Mapping

curl -X POST "https://ordinavo.de/api/connect/v1/inbound/targets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: JOB-2026-000918" \
  -d '{
    "externalId": "JOB-2026-000918",
    "title": "Maintenance visit",
    "customer": {
      "externalId": "CUST-10042",
      "customerNumber": "RRM-001",
      "name": "Rhein-Ruhr Medical Supply"
    },
    "location": {
      "externalId": "LOC-ESSEN-01",
      "name": "Essen Center",
      "city": "Essen",
      "country": "DE"
    }
  }'

C#: import with Customer Mapping

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var client = new HttpClient
{
    BaseAddress = new Uri("https://ordinavo.de/api/connect/v1/")
};

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");

var payload = new
{
    externalId = "JOB-2026-000918",
    title = "Maintenance visit",
    customer = new
    {
        externalId = "CUST-10042",
        customerNumber = "RRM-001",
        name = "Rhein-Ruhr Medical Supply"
    },
    location = new
    {
        externalId = "LOC-ESSEN-01",
        name = "Essen Center",
        city = "Essen",
        country = "DE"
    },
    planning = new
    {
        priority = "High",
        estimatedWorkMinutes = 45
    }
};

var json = JsonSerializer.Serialize(payload);
using var request = new HttpRequestMessage(HttpMethod.Post, "inbound/targets")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json")
};

request.Headers.Add("Idempotency-Key", "JOB-2026-000918");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);

Example workflows

  1. External system imports targets with customer context.
  2. Ordinavo maps customer, location and contact references.
  3. Developer polls ImportJob status.
  4. Manager creates a Smart Route Suggestion.
  5. Mobile employee completes the appointment and submits a visit report.
  6. External system receives VisitReport or Billing webhook events with CustomerContext.