Uploading masterdata

All calls should be authenticated, as explained in Using the Routty API

Synchronizing Masterdata with Routty API

You can automatically synchronize your company and business partner masterdata with Routty through our API endpoints.

API Endpoints for Masterdata

There are three endpoints available to interact with your masterdata in Routty:

• GET /masterdata: Retrieve information about companies and business partners in your tenant.

• POST /masterdata: Create new entries or update existing entries.

• POST /masterdata/delete: Delete a list of entries in the system.

All masterdata operations are performed asynchronously. You can use the GET /masterdata/status/{statusId} endpoint to retrieve the status of an ongoing request.

For all requests, you can specify the accept and content-type headers to control the request and response formats. Both XML and JSON formats are supported.

Retrieving masterdata entries from the system

To retrieve the entries currently present in the system, use the GET /masterdata endpoint. This will return a list of all companies and business partners in your tenant.

• If your tenant does not use business partner masterdata, you will receive the automatically created business partners, which cannot be edited.

• The response will be filtered based on the query parameters provided in the request. All available filters are detailed in the Swagger documentation.

Creating or updating masterdata entries

To create new entries or update existing ones, use the POST /masterdata endpoint.

Your request body should include the masterdata entries in the correct format. After submitting the request, the endpoint will return a statusId, which you can use to track the status of the upload.

Validations Performed Before Upload:

• Format Validation: Ensures the data format is correct.

• Business Partner Masterdata: Checks if business partner masterdata is enabled when uploading customers or suppliers.

• Connector Validation: Verifies that the connector used to upload the data is enabled at the tenant level.

Deleting masterdata entries

Entries are not deleted when using the POST /masterdata endpoint. To delete entries, use the POST /masterdata/delete endpoint. Entries are selected for deletion based on the Routty ID provided during the upload.

• Use the GET /masterdata endpoint to identify which entries are currently in the system.

• The delete endpoint will return a statusId, which can be used to track the status of the deletion request.

Important:

• You cannot delete entries that are part of an active route or access right.

• You cannot delete the last company in a corporate group that still has business partners. In such cases, all business partners in the group must be deleted first.

Retrieving status updates

Since all masterdata operations are asynchronous, you will need to use the GET /masterdata/status/{statusId} endpoint to retrieve the status of your request. You can request the status of any request made in the last 7 days.

Possible status updates:

• Received: Data has been received and queued for processing.

• Success: All entries have been successfully processed.

• DoneWithErrors: Some entries failed during processing; check the FailureReason for details.

• Failed: The import failed; check the FailureReason for details.

Each entry will include a general status and possible failure reasons. If sub-entries are involved, you will receive more detailed information on which part of the upload failed and why.

Possible entry statuses:

• Received: Data received and queued for processing.

• Prepared: Data is being prepared for update.

• InProgress: The update is in progress.

• Success: The entry has been successfully processed.

• DoneWithErrors: Some sub-entries failed.

• Failed: Data could not be processed; check FailureReason.

• Skipped: No changes detected, skipped for performance reasons.

• SkippedByParentError: The parent entry failed; skipped to avoid corrupt data.

• ReceivedForDeletion: The entry is received and waiting for deletion.

• Deleted: The entry has been successfully removed.

Masterdata format

Json

{
  "items": [
    {
      "externalRef": "string",
      "name": "string",
      "companyGroupId": "string",
      "enabled": true,
      "number": "string",
      "type": "string",
      "contactInformation": [
        {
          "primary": true,
          "streetName": "string",
          "streetNumber": "string",
          "poBox": "string",
          "postalCode": "string",
          "city": "string",
          "countryCode": "string",
          "email": "string",
          "phoneNumber": "string"
        }
      ],
      "identifiers": [
        {
          "type": "string",
          "value": "string"
        }
      ]
    }
  ],
  "externalTrackingRef": "string"
}

XML

<?xml version="1.0" encoding="utf-8"?>
<SyncMasterDataRequestDto xmlns="http://schemas.datacontract.org/2004/07/RouttyExpress.ConnectorApi.Controllers">
    <ExternalTrackingRef>string</ExternalTrackingRef>
    <Items>
        <MasterDataEntryDto>
            <CompanyGroupId>string</CompanyGroupId>
            <ContactInformation>
                <ContactInformationDto>
                    <City>string</City>
                    <CountryCode>string</CountryCode>
                    <Email>string</Email>
                    <PhoneNumber>string</PhoneNumber>
                    <PoBox>string</PoBox>
                    <PostalCode>string</PostalCode>
                    <Primary>true</Primary>
                    <StreetName>string</StreetName>
                    <StreetNumber>string</StreetNumber>
                </ContactInformationDto>
            </ContactInformation>
            <Enabled>true</Enabled>
            <ExternalRef>string</ExternalRef>
            <Identifiers>
                <IdentifierDto>
                    <Type>string</Type>
                    <Value>string</Value>
                </IdentifierDto>
            </Identifiers>
            <Name>string</Name>
            <Number>string</Number>
            <Type>string</Type>
        </MasterDataEntryDto>
    </Items>
</SyncMasterDataRequestDto>

Fields

Field	DataType	Restrictions	Required	Info
ExternalRef	String(255)		❌	External reference of the entry. Can be used for tracking of the data
Type	ENUM	Possible values: supplier, customer, company	✅	The type of the entry being uploaded.
Number	String(255)	Unique within tenant for companies; unique within corporate group for customers/suppliers	✅	A unique identifier for this entry.
Name	String(255)		✅	A human readable name for the entry.
CompanyGroupId	String(255)	When uploading customers or suppliers, at least one company with this companyGroupId should already exist.	✅	Logical group for company or business partner.
Enabled	Boolean	true or false	✅	Documents that enter the system for disabled companies or business partners will not be processed in Routty and receive the error status.
ContactInformation	Object	Exactly one entry is required	✅	Information regarding the entry's address. At least one address is required
Identifiers	Object		✅	List of identifiers for tracking the entry. At least one identifier is required

ContactInformation

Identifiers