API Documentation (for version 2 accounts)
PLEASE NOTE: This API is scheduled for retirement. Accounts that are migrated to version 3 of PDM will need to use our latest API. This version of the API is not be forward-compatible. For this reason, we do not recommend that development is done with this version of the API at this time.
Introduction
PDM's Application Programming Interface (API) enables your application to communicate directly with PDM to perform common tasks such as adding and updating customers and deliveries.
Getting Started
Access Keys
An access key must be created via the "Settings" module in the client's PDM web application. Each access key is linked to a single "branch" in the client's account. If you need to interface with multiple branches, several access keys will be required.
Access keys can be configured to limit access via an IP address "white list."
Communicating with the API
The URL for the API is provided when the access tokens are created. Please ask the PDM client to provide the correct URL end-point along with each access token.
Please note that when interacting with the API the URL for the service end-point should NOT have a trailing forward slash (/) at the end.
For example:
https://YOUR_URL_END-POINT/GetSessionToken is correct
https://YOUR_URL_END-POINT/GetSessionToken/ is incorrect
Commands are sent to the API via the HTTP POST method (over SSL).
Commands should be sent in JSON format in the POST request body. Set the HTTP header "Content-Type" to "application/json".
The first command to implement is "GetSessionToken." This command authenticates your API access key, and if successful returns a "session token." Session tokens are required subsequent calls to all other methods in the API.
You will also need to include the client's PDM Company Id with each request.
Keeping Data in Sync
In order to keep data in sync between your application and PDM, the API allows you to include an "external reference" when creating records such as new customers and deliveries via the API. If used, this reference should be unique to each record of that type in your application's database. Existing records can be queried using the "external reference" with subsequent calls to the API.
Additionally, when new records are created the API will return a unique ID for that record in the PDM database. Your application can then log that ID against the matching record in your application's database.
Either of the above methods, or a combination of both, can be used in order to keep data synchronised.
Rate Limiting
To prevent abuse or overloading of the PDM system the API is rate-limited. The following rates apply:
GetSessionToken - maximum of 1 request every 60 minutes.
All other methods - maximum of 1 request every 500 milliseconds.
Since the "GetSessionToken" method is severely rate limited, your application will need to store active session tokens for a minimum of 60 minutes and re-use these during that period. Session tokens remain active for longer than 60 minutes. The exact expiry date and time is provided alongside the session token when it is created via the "GetSessionToken" method. You may choose to log the expiry date and time in your application and only request a new token when the current one has expired.
Example Integration
Example code for C# Using WebClient can be viewed here.
API Method Documentation
Full documentation for all available methods are listed below. Additionally, an API Web Services Description Language (WSDL) file can be found here (insert your end-point url): https://YOUR_URL_END-POINT/wsPDMApi.svc?singleWsdl
