Skip to main content

Sources

Sources connect data in Propeller to the external system it came from. They prevent identifier conflicts when multiple systems integrate with the same Propeller environment.

A source consists of two fields:

  • source: the name of the external system, typically the name of a supplier or ERP system the data originates from (for example MBC for Microsoft Business Central)
  • sourceId: the unique identifier of the resource in that system

The combination of source and sourceId must be unique within the tenant. This means two different systems can use the same identifier without conflict:

A customer with ID 12345 in Microsoft Business Central:

{
  "sourceId": "12345",
  "source": "MBC",
  "name": "Company ABC"
}

The same ID 12345 in Exact Online is a separate record because the source differs:

{
  "sourceId": "12345",
  "source": "EXACTONLINE",
  "name": "Company XYZ"
}

Source representation patterns​

The Propeller REST API uses two patterns for representing sources depending on the context.

Creating resources​

When creating a resource, pass source and sourceId as direct fields in the request body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "source": "MBC",
  "sourceId": "3002196"
}

When sourceId is provided, source is required. When source is provided, sourceId is required.

Reading resources​

GET responses return sources as an array of source objects:

{
  "id": 12345,
  "name": "John Doe",
  "email": "john@example.com",
  "sources": [
    {
      "source": "REST-API",
      "sourceId": "3002196"
    }
  ]
}

This applies to users, usergroups, customers, contacts, companies, products, categories, clusters and most other entities.

Source objects​

Some entities use a source object with name and id properties:

{
  "productSource": {
    "name": "REST-API",
    "id": "T551284"
  }
}

This pattern is used in order items (productSource) and company references (companySource).

Using sources in API operations​

Bulk operations​

Bulk endpoints use the source/sourceId combination to decide whether to create or update a resource. If a resource with that combination already exists, it gets updated. If not, a new resource is created:

POST /v2/users/bulk/sourceId

{
  "contacts": [
    {
      "source": "MBC",
      "sourceId": "3002196",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com"
    }
  ]
}

Lookup by source​

You can retrieve resources using their source identifiers:

GET /v2/contacts/sourceId/3002196?source=MBC

Parent references​

When creating child resources, reference parents using their source information:

{
  "source": "MBC",
  "sourceId": "3002198",
  "parent": {
    "sourceId": "x-123",
    "source": "MBC"
  },
  "firstName": "Jane",
  "lastName": "Smith"
}

Naming conventions​

Source names should be descriptive and consistent. Use uppercase for system names and avoid special characters that might cause URL encoding issues.

See also​