Skip to content
/
Entry - HTML

Passolution Dataservice API (2.0.0)

The Passolution Dataservice API is a RESTful interface to retrieve entry requirements, visa regulations, health information and more for destinations around the world.

Introduction

Target Group

Our API is suitable for suppliers of front and back office systems, as well as tour operators and OTAs who wish to deliver data from Passolution within the framework of the EU Package Travel Directive via their systems to travel agencies or end customers.

Available Languages

The required data can be supplied in different languages. Currently the following languages are supported:

  • German
  • English
  • Dutch
  • Bulgarian
  • Czech
  • Danish
  • Finnish
  • French
  • Greek
  • Hungarian
  • Italian
  • Norwegian
  • Polish
  • Portuguese
  • Romanian
  • Russian
  • Slovak
  • Slovenian
  • Spanish
  • Swedish
  • Turkish

API Requests

Our API is stateless and accepts HTTP GET & POST requests. The request body can be sent in JSON data format.

API Response

The API response is in JSON data format.

HTTP Status Codes

CodeMeaningDescription
200OKThe API request is successful.
204NO CONTENTThere is no content available for the request.
401AUTHORIZATION ERRORInvalid or expired credentials used.
403FORBIDDENNo permission to do the operation.
404METHOD NOT ALLOWEDThe specified method is not allowed.
429TOO MANY REQUESTSNumber of API requests for the 24 hour period is exceeded or the concurrency limit of the user for the app is exceeded.
500INTERNAL SERVER ERRORGeneric error that is encountered due to an unexpected server error.

Authentication

Our API (api.passolution.eu) requires bearer token (access token) to be sent as HTTP Authorization header, ie:

Authorization: Bearer <access-token>

To facilitate bearer / access token generation, our authorization server web.passolution.eu implements OAuth 2 specification. It authenticates Passolution users and then allows users to authorize third party applications (eg: your app) to access Passolution API on their behalf for providing services to them that rely on Passolution data.

If you wish to provide services to our users, kindly contact us to get your OAuth details (Client ID & Secret) which you will need for requesting access to API on a user's behalf.

OAuth Authentication

The Passolution Dataservice API uses OAuth 2.0 protocol, an industry-standard protocol for authentication & authorization of third-party applications (eg: your app) to gain delegated access to API (Passolution) resources on a user's (Passoution) behalf.

OAuth Benefits

  • Third-party applications are not required to handle or store user credentials, which can be a security risk.
  • Third-party applications gain delegated access, i.e., access only to resources authorized by user.
  • Users can revoke an application's access anytime.
  • OAuth 2.0 access tokens expire after a set period of time which reduces risk, eg: when old access tokens are leaked in a security breach. If an application faces a security breach, all its access tokens can be disabled at once (preventing unauthorized access) without affecting user's or other application's access.

How OAuth 2.0 works?

OAuth Process Open Full Image

OAuth Terminology

You should familiarize yourself with following terms to help understand the OAuth authorization flow before you start using Passolution Dataservice API:

Protected Resources

The Passolution Dataservice resources, such as Entry, Visa, Transit Visa & Health Requirements etc.

Resource Server

The Passolution API Service (api.passolution.eu) that hosts protected resources.

OAuth Client

An application (eg: your app) implementing OAuth protocol that sends requests to the Resource Server (Passolution API) to access protected resources on behalf of a Passolution user.

Authorization Server

Passolution Service (web.passolution.eu) that authenticates users and allows users to authorize an OAuth Client (your app) to access Resource Server (Passolution API) on their behalf. After authorization, the OAuth Client (your app) can contact this server to get user's Access Token.

Access Token

Access Token allows access to Resource Server (Passolution API) on a user's behalf.

It is a long string of seemingly random characters that actually is encoded data which allows Resource Server (Passolution API) to know which OAuth Client is accessing the API service on which user's behalf.

Refresh Token

A token that can be used to obtain a new Access Token by contacting the Authorization Server (web.passolution.eu). A new token should be generated using the refresh token before the refresh token expires.

Client ID

A unique ID assigned to an OAuth Client application used in OAuth protocol.

Client Secret

A shared secret value that allows Authorization Server (web.passolution.eu) to authenticate an OAuth Client application during OAuth protocol data exchange.

Authorization Code

Once a Passolution user authorizes your OAuth Client application, our Authorization Server (web.passolution.eu) will generate and send an Authorization Code to your application. Your application can then contact the Authorization Server to exchange this Authorization Code with Access Token & Refresh Token for the Passolution user.

Grant Types

Grant Types are different ways an OAuth Client (eg: your application) can request access token. There are several OAuth Grant Types which are described below.

OAuth Grant Types

OAuth Grant Types are different ways you can get access token for your own Passolution account or on behalf of a Passolution user. They have different limitations and use cases which are explained below.

Authorization Code

This is the most widely used grant type for applications that require delegated access (access on a user's behalf) and have its own servers that can directly interact with our Authorization Server (web.passolution.eu) to get access tokens.

Authorization Code Grant With PKCE

This grant type is used when you don't have your own servers that can securely store your OAuth Client Secret & user's access tokens but still need delegated access on Passolution user's behalf.

For example, if you have a Single Page App without backend servers, you can get access token with this grant type and store the access token for user in their browser itself (Web Storage API).

Client Credentials

This grant type can be used to get access token for your own Passolution account only. Kindly note that this grant type does not provide access on other Passolution user's behalf.

Requesting Access Token

Note: If you are unsure which Grant Type / method of requesting Access Token you need to use, kindly go over the 'OAuth Grant Types' section first.

If you don't have your OAuth details, kindly contact us with the following details about your application:

DetailExplanation
Website:Website for general information about your product / service,
eg: https://example.com
Redirect URL:Endpoint where your application / service will handle OAuth responses sent by Passolution Authorization Server
eg: https://example.com/handle-oauth-authorization
Grant Type:The Grant Type your application needs to use, check 'OAuth Grant Types' section for details.
eg: Authorization Code

We will provide you the following OAuth details after setting up OAuth Client for your application:

DetailExplanation
Client ID:A unique ID assigned to your OAuth Client application to be used in OAuth protocol.
Client Secret:A shared secret value that allows Authorization Server (web.passolution.eu) to authenticate your OAuth Client application during OAuth protocol data exchange.
It should not be stored outside of your secure servers

We will now go over the OAuth Grant Types (method of requesting Access Token) and discuss how they can be implemented in your application.

Here are some endpoints on our OAuth Authorization Server that your application will need to interact with:

OAuth EndpointURL
Authorization URL:https://web.passolution.eu/oauth/authorize
Token URL:https://web.passolution.eu/oauth/token
Token Refresh URL:https://web.passolution.eu/oauth/token

Authorization Code

For this grant type (read 'OAuth Grant Types' section), your application will have to redirect users to Passolution's Authorization Server's Authorization URL with following parameters:

ParameterDescription
client_idYour OAuth Client ID
redirect_uriRedirect URL that you provided us when requesting OAuth details for your application.
response_type'response_type' parameter should be set to 'code' for Authorization Code Grant Type.
scope'scope' parameter should be set to '*' to request access to all API resources.
state'state' parameter should contain a random string that you store to user's session storage and verify later when handling authorization response received on your Redirect URL endpoint sent as redirect_uri parameter.

state parameter code logic example:

const userState = RandomString::generate(); // eg: G8TZWEjUmuWFZgtHZ5gs
UserSession::set('user-oauth-state', userState);
Redirect::toUrl('https://web.passolution.eu/oauth/authorize?...&state=' + userState);

Example:

https://web.passolution.eu/oauth/authorize?client_id=your-client-id&redirect_uri=https://your-website.example.com/handle-oauth-authorization&response_type=code&scope=%2A&state=random-state-for-user

At this stage, on our Authorization Server, the user will be asked to login (if not already logged in) and then they will be able to decide if they want to allow access to your application. Once they allow access, they will be redirected to your Redirect URL with following parameters:

ParameterDescription
stateThis is the random string that you sent when redirecting user to Authorization Server. You should have stored it in user's session storage and should now confirm that the values received matches the stored value.
codeThis is authorization code that you can use to get access token as explained in next step.

Example:

https://your-website.example.com/handle-oauth-authorization?state=random-state-that-was-sent-for-user&code=authorization_code

state parameter verification logic example:

// stored earlier when redirecting user for login
const userState = UserSession::get('user-oauth-state');
if(userState == Url::getParameter('state')) {
  // exchange authorization code for Access Token as described below.
}
else {
  throw Exception('OAuth Login: Invalid state parameter received.');
}

To exchange the authorization code (code parameter received on Redirect URL) for Access Token & Refresh Token for the user, you have to make a POST request to Authorization Server's Token URL (https://web.passolution.eu/oauth/token), eg:

POST https://web.passolution.eu/oauth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your-website.example.com/handle-oauth-authorization",
  "code": "authorization-code"
}

Data fields used in the request body above are described below:

ParameterDescription
client_idYour OAuth Client ID
client_secretYour OAuth Client Secret
It should not be stored outside of your secure servers
grant_type'grant_type' field should be set to 'authorization_code' for the Authorization Code Grant Type
redirect_uriRedirect URL of the endpoint where the authorization response was received.
codeThe authorization code received as 'code' parameter to your Redirect URL endpoint

The Token URL endpoint will respond with JSON response containing following fields:

{
  "expires_in": 31536000,
  "access_token": "eyJ...",
  "refresh_token": "def..."
}
ParameterDescription
expires_inNumber of seconds after which the access token will expire.
access_tokenAccess Token for the User
refresh_tokenRefresh Token for the User which can be used to generate new Access Token before expiry

Authorization Code Grant With PKCE

For this grant type (read 'OAuth Grant Types' section), your application will have to redirect users to Passolution's Authorization Server's Authorization URL with following parameters:

ParameterDescription
client_idYour OAuth Client ID
redirect_uriRedirect URL that you provided us when requesting OAuth details for your application.
response_type'response_type' parameter should be set to 'code' for Authorization Code Grant Type.
scope'scope' parameter should be set to '*' to request access to all API resources.
state'state' parameter should contain a random string that you store to user's session storage and verify later when handling authorization response received on your Redirect URL endpoint sent as redirect_uri parameter.
code_challenge'code_challenge' parameter value should be Base64 encoded value (URL safe characters) of SHA256 hash of a randomly generated 'Code Verifier'. The Code Verifier should be randomly generated string of length between 43 and 128 characters. Trailing '=' characters as well as any whitespace or line breaks should be removed from the Base64 encoded value.
See code logic below
code_challenge_method'code_challenge_method' parameter should be set to 'S256' specifying the SHA256 hash algorithm being used.

state & code_challenge parameter code logic example:

const userState = RandomString::generate(); // eg: G8TZWEjUmuWFZgtHZ5gs
UserSession::set('user-oauth-state', userState);

const codeVerifierLength = 128;
const codeVerifier = RandomString::generate(codeVerifierLength); // eg: L5nD...UKbN
UserSession::set('user-oauth-code-verifier', codeVerifier);

const hashBinary = SHA256::hashAsBinary(codeVerifier); // SHA256 hash as binary data
let codeChallenge = Base64::encode(hashBinary); // Base64 encode SHA256 hash

// Removing trailing '=' characters and replace URL unsafe characters ('+' & '/')
codeChallenge = String::removeFromEnd(codeChallenge, '=');
codeChallenge = String::replace(codeChallenge, '+', '-');
codeChallenge = String::replace(codeChallenge, '/', '_');

Redirect::toUrl('https://web.passolution.eu/oauth/authorize?...&state=' + userState + '&code_challenge=' + codeChallenge);

Example:

https://web.passolution.eu/oauth/authorize?client_id=your-client-id&redirect_uri=https://your-website.example.com/handle-oauth-authorization&response_type=code&scope=%2A&state=random-state-for-user&code_challenge=code-challange&code_challenge_method=S256

At this stage, on our Authorization Server, the user will be asked to login (if not already logged in) and then they will be able to decide if they want to allow access to your application. Once they allow access, they will be redirected to your Redirect URL with following parameters:

ParameterDescription
stateThis is the random string that you sent when redirecting user to Authorization Server. You should have stored it in user's session storage and should now confirm that the values received matches the stored value.
codeThis is authorization code that you can use to get access token as explained in next step.

Example:

https://your-website.example.com/handle-oauth-authorization?state=random-state-that-was-sent-for-user&code=authorization_code

state parameter verification logic example:

// stored earlier when redirecting user for login
const userState = UserSession::get('user-oauth-state');
if(userState == Url::getParameter('state')) {
  // exchange authorization code for Access Token as described below.
}
else {
  throw Exception('OAuth Login: Invalid state parameter received.');
}

To exchange the authorization code (code parameter received on Redirect URL) for Access Token & Refresh Token for the user, you have to make a POST request to Authorization Server's Token URL (https://web.passolution.eu/oauth/token), eg:

POST https://web.passolution.eu/oauth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your-website.example.com/handle-oauth-authorization",
  "code": "authorization-code",
  "code_verifier": "code-verifier"
}

Data fields used in the request body above are described below:

ParameterDescription
client_idYour OAuth Client ID
grant_type'grant_type' field should be set to 'authorization_code' for the Authorization Code Grant Type
redirect_uriRedirect URL of the endpoint where the authorization response was received.
codeThe authorization code received as 'code' parameter to your Redirect URL endpoint
code_verifierThe Code Verifier (non hashed value) that we randomly generated earlier for user and stored in session storage.

The Token URL endpoint will respond with JSON response containing following fields:

{
  "expires_in": 31536000,
  "access_token": "eyJ...",
  "refresh_token": "def..."
}
ParameterDescription
expires_inNumber of seconds after which the access token will expire.
access_tokenAccess Token for the User
refresh_tokenRefresh Token for the User which can be used to generate new Access Token before expiry

Client Credentials

Since this grant type (read 'OAuth Grant Types' section) only allows access to your own account, you only need your OAuth Client ID & Client Secret to generate an Access Token using the Token URL endpoint (https://web.passolution.eu/oauth/token):

POST https://web.passolution.eu/oauth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials"
}
ParameterDescription
client_idYour OAuth Client ID
client_secretYour OAuth Client Secret
It should not be stored outside of your secure servers
grant_type'grant_type' field should be set to 'client_credentials' when using Client Credentials Grant Type

The Token URL endpoint will respond with JSON response containing following fields:

{
  "expires_in": 31536000,
  "access_token": "eyJ..."
}
ParameterDescription
expires_inNumber of seconds after which the access token will expire.
access_tokenAccess Token for the OAuth Client Passolution Account

Using Access Token

The Access Token received from Token URL can be used to access API by sending it in Authorization header as a Bearer token, eg:

GET https://api.passolution.eu/api/v2/infosystem/passolution
Authorization: Bearer eyJ...

Refreshing Access Token

The Refresh Token received with Access Token can be used to get a new Access Token & Refresh Token before the expiry by making a POST request to Authorization Server's Token Refresh URL (https://web.passolution.eu/oauth/token):

Note: A Refresh Token can be used only once. Make sure to store new Refresh Token received when refreshing an Access Token for future use.

POST https://web.passolution.eu/oauth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "refresh_token",
  "refresh_token": "refresh-token-value"
}

Note: The Token Refresh URL is rate limited to 300 requests per minute.

ParameterDescription
client_idYour OAuth Client ID
client_secretYour OAuth Client Secret
It should not be stored outside of your secure servers
grant_type'grant_type' field should be set to 'refresh_token' when using refresh token for generating new Access Token
refresh_tokenThe refresh token that was received when exchanging 'authorization code' for Access Token

The Refresh Token URL endpoint will respond with JSON response containing following fields:

{
  "expires_in": 31536000,
  "access_token": "eyJ...",
  "refresh_token": "def..."
}
ParameterDescription
expires_inNumber of seconds after which the new access token will expire.
access_tokenNew Access Token for the User
refresh_tokenNew Refresh Token for the User which can be used to generate new Access Token again

Note: A Refresh Token can be used only once. Make sure to store the new Refresh Token received in response for future use.

Important Note

OAuth Client Secret, Access Tokens / Bearer Tokens must be kept confidential.

DO NOT expose these details anywhere in public forums, public repositories or on your website's client-side code like HTML or JavaScript. Exposing it to the public may lead to data theft or loss.




Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://passolution.eu
Passolution
info@passolution.eu
Languages
Servers
https://api.passolution.eu/api/v2/

API Server

Operations

Account Information

Operations

Basic Data - General

Operations

Basic Data - Entry Requirements

Operations

Infosystem

Operations

Entry Requirements

Operations

Entry - JSON

Request

Security
oAuth or bearerAuth
Query
langstring

Language code for response content.

Default "de"
Enum"de""en""fr""it""nl""pl""es""pt""ru""bg"
Example: lang=en
countriesArray of strings

Country codes as array or comma separated.

Example: countries=TR&countries=ZA&countries=AE
natArray of strings

Traveller nationality codes as array or comma separated.

Example: nat=DE&nat=AT
Bodyapplication/json
filtersobject
curl -i -X POST \
  'https://api.passolution.eu/api/v2/content/entry/json?lang=en&countries=TR%2CZA%2CAE&nat=DE%2CAT' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "documents": {
        "document_code": {
          "entry_allowed": true
        }
      },
      "additional_info": {
        "list": {
          "code": {
            "status": "not_required"
          }
        }
      }
    }
  }'

Responses

Country Entry Information in JSON Format

Bodyapplication/json
recordsArray of objects
requestidstring(uuid)

Unique Request ID identifying this request.

responsetimenumber

Time taken to generate response.

Response
application/json
{
  "records": [
    { … }
  ],
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "responsetime": 0
}

Entry - HTML

Request

Security
oAuth or bearerAuth
Query
langstring

Language code for response content.

Default "de"
Enum"de""en""fr""it""nl""pl""es""pt""ru""bg"
Example: lang=en
countriesArray of strings

Country codes as array or comma separated.

Example: countries=TR&countries=ZA&countries=AE
natArray of strings

Traveller nationality codes as array or comma separated.

Example: nat=DE&nat=AT
target-devicestring

Send this parameter if the content is to be displayed on a device with limited screen space.

Value"mobile"
Bodyapplication/json
filtersobject
curl -i -X POST \
  'https://api.passolution.eu/api/v2/content/entry/html?lang=en&countries=TR%2CZA%2CAE&nat=DE%2CAT&target-device=mobile' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "documents": {
        "document_code": {
          "entry_allowed": true
        }
      },
      "additional_info": {
        "list": {
          "code": {
            "status": "not_required"
          }
        }
      }
    }
  }'

Responses

Country Entry Information in HTML Format

Bodyapplication/json
recordsArray of objects
requestidstring(uuid)

Unique Request ID identifying this request.

responsetimenumber

Time taken to generate response.

Response
application/json
{
  "records": [
    { … }
  ],
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "responsetime": 0
}

Entry - Text

Request

Security
oAuth or bearerAuth
Query
langstring

Language code for response content.

Default "de"
Enum"de""en""fr""it""nl""pl""es""pt""ru""bg"
Example: lang=en
countriesArray of strings

Country codes as array or comma separated.

Example: countries=TR&countries=ZA&countries=AE
natArray of strings

Traveller nationality codes as array or comma separated.

Example: nat=DE&nat=AT
Bodyapplication/json
filtersobject
curl -i -X POST \
  'https://api.passolution.eu/api/v2/content/entry/text?lang=en&countries=TR%2CZA%2CAE&nat=DE%2CAT' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "documents": {
        "document_code": {
          "entry_allowed": true
        }
      },
      "additional_info": {
        "list": {
          "code": {
            "status": "not_required"
          }
        }
      }
    }
  }'

Responses

Country Entry Information in Text Format

Bodyapplication/json
recordsArray of objects
requestidstring(uuid)

Unique Request ID identifying this request.

responsetimenumber

Time taken to generate response.

Response
application/json
{
  "records": [
    { … }
  ],
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "responsetime": 0
}

Country Information

Operations

Travel Information

Operations

Individual Content

Operations

Tour Operator Content

Operations