# Introduction

This guide will walk you through the steps to get started with accessing our internal systems and utilizing our comprehensive portfolio of Products and APIs in the shipping industry. By following these instructions, you will be able to harness the power of real-time shipping information and seamlessly integrate it into your software applications.

# Step 1: Registration

To begin your journey with our API Developer Portal, the first step is to register for an account. Registration is essential to access the platform's functionalities and ensures that you have a personalized experience. Follow these steps to create your account:

Visit the API Developer Portal website (opens new window).
Click on the "Login" button to start the registration process.
Then select ‘Not yet registered?’
Fill in the required details: Name, Last name, Phone number, Company name, Address, City, Postal code, and Country.
Click on 'Continue' button.
In this step, provide your e-mail address and click on the “Send verification code” button. Before moving forward, check your mailbox for a verification code, copy and enter it in the form below, and click the 'Verify code' button.
Then please select your user role, provide the desired password, and confirm it. Finally, to finalize the registration process, it is required to give your consent to Privacy Terms and Terms of Use, only then you can click on the 'Continue' button.
Once you have completed the registration, Hapag-Lloyd will verify your account. You will receive an email confirmation with further instructions. After verification, you will gain access to additional features such as application creation and subscription requests.

# Step 2: Create an application

To access the APIs and obtain individual API credentials (ClientID and Client Secret), you need to create an application. An application acts as an interface between your software and our APIs. Please note that functionalities mentioned in this step and onward will only be available after your account has been verified and granted permission.
Please follow the steps below to create your application successfully:

# Authorization Code Application Type (Portals / 3rd parties)

Log in to your account on the API Developer Portal.
Navigate to the "Applications" section.
Click on the "Create New Application" button.
Select “Authorization Code Type application type and choose whether it is a “Web Application” or “Single Page Application” (SPA) and provide the necessary details.
Submit the form.
After submitting your form, our Hapag-Lloyd experts will receive your request, and the application status will be marked as pending. Please note that the verification process may take over one week. Once it is completed, we will notify you via email.
After receiving an email with the approval, Click on the “Assign client secret” button, to assign Client-Secret* to your application.
Upon successful application creation, you will be granted unique API credentials, including a Client-ID and Client-Secret, which you will later use to authenticate your API requests.

^{(*please be aware that Client-Secret will only be shown once, so please save it and keep it somewhere safe.)}

# Client Credentials Application

Log in to your account on the API Developer Portal.
Navigate to the "Applications" section.
Click on the "Create New Application" button.
Select “Client Credentials“ application type.
Provide a meaningful name for your application.
Please ensure you provide a valid and accessible organizational email address for the new Technical API user. This email will be required for authentication purposes within our system.
Submit the form.
To activate your newly created Technical API User, use the confirmation link* that was sent to the email address you provided earlier.
If you are facing problems with your confirmation link, please go back to ”Applications” and click ”Resend verification mail”, then after receiving an e-mail, click on ”Confirm my API Developer Portal registration”.
Upon success, you should be granted an individual Client-ID in the 'Applications' view.
Click on “Assign client secret” button, to assign Client-Secret*** to your application.
Upon successful application creation, you will be granted unique API credentials, including a Client-ID and Client-Secret, which you will use to authenticate your requests.
^{(* Please be advised that e-mail link will be valid only 1 hour.)}
^{(** Limited to 3 times.)}
^{(*** Please be advised that Client-Secret will only be shown once, so please save it and keep it somewhere safe.)}

# Step 3: Subscriptions

Subscriptions are essential to access specific API Products and define usage plans (rate limits) for your individual use case. To access the portal's functionalities, ensure that your subscription request to the given product is approved. Follow these steps to set up your subscription:

Visit the API Portal's main page and choose an API Product (individual tile) you are interested in. Or, hover over the “API Products” in the topmost navigation and pick a specific product from there.
Inside the product detail section, click “Create new subscription”* button.
Choose your existing application or create a new one for the subscription.
Pick the right usage plan or rate limit for your requirements.
Review the request summary.
Click on ”Submit” to submit your subscription request.

^{(* Please be advised that the button will only be accessible if your account has been verified.)}

# Step 4: Subscription Approval

After you send your subscription request, Hapag-Lloyd will review it.
You will get a notification about the status of your request.
If it is approved, you can start to use all the APIs included in the subscribed product, using your app's credentials.
If it is rejected, you will receive a detailed explanation of why.

# Step 5: Accessing the APIs

Congratulations! You are now ready to access our APIs and retrieve real-time shipping information. To initiate API requests successfully, ensure that you include the following headers in each individual request, using the credentials assigned to your created application.

X-IBM-Client-ID: %YOUR_CLIENT_ID%"
X-IBM-Client-Secret: %YOUR_CLIENT_SECRET%

These headers serve as your individual credentials and are essential for proper API request authentication. The gateway will authenticate and obtain a token, which is then utilized within our internal system.

# Example request:

curl -X PUT
-H 'Accept: application/json'
-H "Content-Type: application/json" 
-H "X-IBM-Client-ID: %YOUR_CLIENT_ID%" 
-H "X-IBM-Client-Secret: %YOUR_CLIENT_SECRET%" 
"https://api.hlag.com/hlag/prod-public/v1/transport-work-orders/{work_order_number}/actual-arrivals"

Make sure to replace %YOUR_CLIENT_ID% and %YOUR_CLIENT_SECRET% with your actual Client-ID and Client-Secret values from created application. This ensures a secure and authenticated connection to our API endpoint.

# Step 6*: Onboarding your API Users for Authorization Code Type Application (Portals / 3rd Parties)

To help your users benefit from the connection you have set up, they must complete the registration process successfully with Hapag-Lloyd Step: 1 Registration.

That's it! You have now completed the Getting Started guide for the Hapag-Lloyd API Developer Portal. We hope this guide has helped you on your journey to harness the power of real-time shipping information and integrate it seamlessly into your software applications.

If you have any questions or need assistance, do not hesitate to reach out to our support team. Happy coding!

← Introduction Introduction →