Public API & Integrations

When to use

The Peripass API is a REST API. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

You can make requests to the Peripass API from a terminal or browser, or from within any code. The examples in the documentation use curl, but you can use wget, libcurl or any other method to GET and POST in your preferred language. Your preferred coding language should include libraries to support making HTTP requests and parsing responses.

Main idea

• We have the possibility to push data to other systems. We can map data in the format in which the receiving party expects this. This makes use of Triggers & Actions .

• We expect other systems to push data to us. We expect other systems to map data in the format in which we expect this. This makes use of our public API.

• We have a standard integration with Transporeon and with Alpega:

  • Transporeon TMS integration

  • Alpega TMS (Transwide) integration

Won’t do

From external to Peripass

• Only our public API is supported, meaning REST API (JSON).

• We do not provide a field mapper for incoming API calls. We expect the other party to adapt to our public API. We are only able to map profiles & operation types.

• We do not accept EDI messages.

• We do not subscribe to message services.

• We do not poll external systems.

From Peripass to external

• We only support SOAP (xml) or REST (json) API methods.

• We do not send CSV files or other formats.

• We do not send IDOC messages to SAP.

• EDI is a general protocol that can have many flavours. If the flavour used by the customer accepts messages of the HTTP protocol, it might be possible to integrate, however specific testing per customer will be needed. Contact support for more information.

More information

Swagger documentation

Public API: Our swagger documentation is publicly available and can be found on: https://restapiprd.peripass.app/documentation/ui/?tenant=demo.

Be aware, there is a second API, used for automating Yard Location Sensors, which can be found here: Dock sensors | Using-wheel-blocks. This dedicated API allows to send updates without headers, as this is a requirement for API calls being send by an Axis I/O module.

Where to find your API key?

Request your API key through support

All calls to the Peripass API need to be authenticated. An authorization header needs to be added to each request. You’ll need an API key to construct this header. Every tenant has at least one API key, which can be found in Configuration > General settings > Integrations.

Contact support to request new API keys. We advise to have a dedicated API key for each integration.

Default profile for /createorupdate method

To avoid that integration partners need to use different API methods to create or update visitors (after checking that the visitor already exists), a specific API method was created:

This method will create a new visitor with the “default” profile that can be configured in the “General Settings” of the tenant:

If no default profile is configured, the visitors/createorupdate method will FAIL with a clear error message that the default profile is missing.

Profile & operation type mapping

To make simplify the integration with host systems, the API visitors/createorupdate method will create a visitor with a default profile. This avoids the host system to understand the business logic of the different profiles. When the visitor is automatically created, it is possible to map the correct profile in Peripass using Triggers & Actions.

Using Triggers & Actions it is possible to remap the a profile to the desired Peripass profile after creation. Create a rule for each profile / operation combo:

1. Trigger: When a visitor is assigned a profile (choose new + updated assigned profile)

2. Conditions: Use “field compared to value” to use a combination of custom fields to decide the profile.

3. Action: Change profile.

The “Change profile” action allows you to change the profile and the operation type of a visitor.

More information on profile: Visitor profile

More information on operation type: Yard Asset Management | Operation-Types

A note on (custom) field validation when inserting visitors using the API

When pre-registering visitors through the API, be aware that the data model of a visitor can be different per profile. In general the API will validate custom fields as follows:

• When trying to insert fields that exist in Peripass but have a bad formatting

  • the API call will Fail ❌ when the query is creating a visitor and the field is mandatory

  • the API call will succeed ✅ with remarks when the query is creating a visitor and the fiels is optional

  • the API call will succeed ✅ with remarks when the query is updating a visitor

• When trying to insert fields that don’t exist in Peripass: the API call will succeed ✅ with remarks that the non-existing fields are ignored.

• When trying to insert fields that exist in Peripass but are not linked to the current profile: the API call will succeed ✅ and non-linked fields are saved as extra fields. The formatting is validated as normal.

• There is an exception in the behavior for the ANPR field: ANPR camera integration | License-plate-format

Field clearance

Fields can be cleared by providing an empty string:

“field_name”: ““

When providing null as field value, the field update will be ignored.

Who should be the leading system?

We advise following ownership rules:

Automation

The trigger “when a visitor is assigned a profile…” will be fired when an the planning (only when the profile validity dates are changed, not of the slot start or end hours are affected) are updated using the API.

It is best practice to reset a visitor to expected when the profile validity is updated. If you do not do this, the visitor will not be in the status expected and the driver won’t be able to register on his newly planned day.

More on automation can be found here: Triggers & Actions

Rate limiting

Rate limiting is in place to manage API usage, ensure fairness, and protect system resources.

There is a limit of 500 API calls per 1-minute window per site. (thus a tenant with 3 sites can do 1500 calls per 1-minute window)

When the limit is reached, API requests will fail. The API call needs to be retried by the integrator after the reset time, which will be indicated in the rate limit response.

Information about your specific rate limit information will be provided in the headers of the API responses. More details can be found in our public API documentation.

Best practices:

• Respect the rate limits: the integration should be designed to never run into a rate limit. Spread your calls throughout time if necessary.

• Implement caching strategies to reduce unnecessary requests.

• Implement delayed retries for critical API calls.

When an integration hits an API rate limit, an error log will be added to the integration log (only once per 1-minute window).

Special integration types

Hot folder integration

Many customers request whether we support hot folder integrations. We do not support this, however the customer can build this easily themselves (either using their own IT department or by leveraging azure consultants):

• "hot folder integrations" are typicall old fashioned integrations that are very popular with SAP, as end users can use this without a lot of technical knowledge (they don't need

• Big companies can fix this by start using middleware (e.g. Microsoft bizztalk or SAP PI/PO). This is a very powerfull solution, however very expensive

• Smaller companies can use the example above to fix such an integration. This can be setup by an integrator, NOT by peripass.

Sharepoint integration

More information here Sharepoint integration using Power Automate

How to configure

See API integration guidelines & best practices for more detailed information.