Introduction
C Teleport is a travel management platform. In order not to enter passenger data during the booking platform, C Teleport needs to collect this data from your data sources.
Any method and any data format
We support wide variety of data sources and variety of data formats.
We understand that every company has its own requirements, data formats and existing software. We can use use any method of integration that works better for your needs.
Here is an overview of possible options for data exchange:
1. Web Services / API (recommended)
You create a WebService/API. C Teleport is requesting this API to collect required data. Format of the response can be JSON (recommended), XML, CSV or other formats.
2. File export
You can export required data into a file every 30 minutes. Then you should share this file with C Teleport by using FTP or email.
C Teleport will import and use this data every 30 minutes.
Supported file formats: JSON, XML, CSV, others
3. Access to database
You can provide C Teleport with an access to your database and C Teleport will be pulling all necessary data from it. We can work with all kinds of databases, including MS SQL and MySQL.
What can be integrated at all?
- Passenger data - you don't have to enter passenger data anymore
- Whole crew change data - you don't have to enter airports or dates
- Entering flight data into your crewing software - after booking, cancelling or changing the flight, it's data is automatically sent back to your crewing software
- Search flights from your crewing software - when you have finished crew planning, you click one button and see all flights for the whole crew change
Recommended timeline
We always recommend splitting integration into parts. It is best to begin with the easiest and fastest integration and then develop deeper integrations later. Here is the suggested timeline:
- ~4 hours One seaman suggestion - Article 2.1
- ~4 hours Crew change data integration - Article 2.2
- ~20 hours Sending flight data back to the crewing software - Article 4
- Pushing data to us - Article 3 - implementation time depends on your software
It is completely OK to have only basic integrations and not have others. But it is absolutely essential to have Article 2 integrated properly. It brings most efficiency to the process.
1. One seaman integration (required)
This is the most basic integration. It is also the minimum required integration to start using C Teleport. It should take between 4 and 20 hours depending on crewing software infrastructure. If you estimate more time, please get in touch with us to discuss options.
Here, what crew managers will see:
When users enter passenger data while booking, we suggest surnames of seamen from your crewing software. Then users don't have to enter data manually and, therefore, avoid mistakes. C Teleport uses the first entered letters to find seamen for the suggestions.
Sample set of data in JSON format
[
{
"last_name": "Smithsen",
"first_name": "John",
"dob": "1978-12-03", // YYYY-MM-DD format
"nationality": "GB", // 2-char ISO code
"gender": "M",
"doc_country": "GB", // 2-char ISO code
"doc_number": "UK36276372323",
"doc_expire": "2019-04-22", // YYYY-MM-DD format
"home_airport": "LON", // IATA-code of the home airport
"email": "smithsen@gmail.com", // Optional
"id": "AS32231", // Optional back-sync ID
},
{
"last_name": "Smith",
"first_name": "Eugene",
"dob": "1976-11-12", // YYYY-MM-DD format
"nationality": "NL", // 2-char ISO code
"gender": "M",
"doc_country": "NL", // 2-char ISO code
"doc_number": "NL637643742",
"doc_expire": "2021-03-04", // YYYY-MM-DD format
"home_airport": "LON", // IATA-code of the home airport
"email": "eugene.smith@gmail.com", // Optional
"id": "SM3233", // Optional back-sync ID
}
]
Required data for one-seaman integration
| Parameter | Format | Description |
|---|---|---|
| last_name | string | Last name |
| first_name | string | First name |
| dob | YYYY-MM-DD | Date of birth |
| nationality | 2 letters | Nationality. 2-letter country code. Standard ISO-3166-1 alpha-2. |
| gender | M or F | Gender |
| doc_country | 2 letters | Passport issuance country. 2-letter country code. Standard ISO-3166-1 alpha-2. |
| doc_number | string | Passport number |
| doc_expire | YYYY-MM-DD | Passport expiry date |
| home_airport | 3 letters | IATA code of the closest airport for the seaman. |
| string | Optional. Email of the seaman | |
| id | string | Optional. ID number of the seamen for backwards synchronisation |
Option 1.1: API or webservice
Sample GET request to your webservice
GET http://yourcompany.com/api/suggest_seaman?surname=SMITH
Here is the desired workflow:
You develop a webservice that will respond to GET requests. You provide us with the URL address of the web service and establish security measures.
Http auth password protected access or IP whitelist will do.
Your webservice responds with a list of seamen, who are matching the surname.
Despite we recommend JSON format, we can accept any format of data and convert it to our required format on our side. So your API may respond with JSON, XML, SOAP, CSV, plaintext or virtually any other format. In case of missing data crewing managers will have to enter it manually.
Option 1.2: Cache data
You develop and API that allows C Teleport caching all seamen data on a regular basis. Normal frequency is every hour. Then C Teleport retrieves data from you regularly, stores all cached data and serves users suggestions from cache. This options is the fastest in terms of performance.
Option 1.3: File export
You regularly export a file with all seamen data. Then you deliver the file to a special email provided by C Teleport or upload it to FTP. C Teleport will receive the file and store the data in cache. Users will receive suggestions from this cache.
Option 1.4: Web-based scraping
C Teleport may use your provided login and password to log into the crewing software and retrieve the required information from there. The data will be stored in C Teleport cache. It will refresh the data regularly.
2. Crew change integration
Sample request to your webservice
GET http://yourcompany.com/api/crew_change?date=2017-06-03
Sample response
[
{
"vessel": "CMA CGM Passat",
"flag": "GB",
"onsigners": [
{
"id": "231",
"last_name": "Smithsen",
"first_name": "John",
"dob": "1978-12-03",
"nationality": "GB",
"gender": "M",
"doc_country": "GB",
"doc_number": "UK36276372323",
"doc_expire": "2019-04-22",
"home_airport": "LON",
"email": "smithsen@gmail.com",
"arrive": "2017-06-03"
}
],
"offsigners": [
{
"id": "4343",
"last_name": "Petrov",
"first_name": "Sergey",
"dob": "1965-11-22",
"nationality": "RU",
"gender": "M",
"doc_country": "RU",
"doc_number": "RU3627362332",
"doc_expire": "2019-08-11",
"home_airport": "LED",
"email": "petrov@mail.ru",
"depart": "2017-06-03"
},
]
}
]
When users enter a vessel and a date for a crew change, C Teleport will pre-fill all airports and passenger data.
This is the desired workflow:
Option 2.1 API or webservice
You have to develop and API or webservice.
C Teleport will be sending a GET request to your webservice with a date entered by a user.
Based on the date, your webservice prepares the data on all onsigners and offsigners, lined up for this date.
Response may contain crew changes for multiple vessels.
What data do you need?
Your webservice has to collect 3 pieces of data: 1. vessels data, which have crew changes on the requested date 2. data on on-signers on the requested date 3. data on off-signers on the requested date
Data on seamen has the same format as used across this document. Some new fields are as follows:
| Parameter | Format | Description |
|---|---|---|
| vessel | string | vessel name |
| flag | 2 letters | vessel flag |
| depart, arrive | YYYY-MM-DD | date of departure or arrival form/to the airport of crew change |
Option 2.2 Initiate search from your software
Sample HTML form
<form action="https://app.cteleport.com/integrations/search" method="POST">
<input type="hidden" name="vessel" value="CMA CGM Passat">
<input type="hidden" name="flag" value="GB">
<input type="hidden" name="change_airport" value="AMS">
<input type="hidden" name="onsigners[0][arrive]" value="2017-06-03">
<input type="hidden" name="onsigners[0][last_name]" value="Smithsen">
<input type="hidden" name="onsigners[0][first_name]" value="John">
<input type="hidden" name="onsigners[0][dob]" value="1978-12-03">
<input type="hidden" name="onsigners[0][nationality]" value="GB">
<input type="hidden" name="onsigners[0][gender]" value="M">
<input type="hidden" name="onsigners[0][doc_country]" value="GB">
<input type="hidden" name="onsigners[0][doc_number]" value="UK36276372323">
<input type="hidden" name="onsigners[0][doc_expire]" value="2019-04-22">
<input type="hidden" name="onsigners[0][home_airport]" value="LON">
<input type="hidden" name="onsigners[0][email]" value="smithsen@gmail.com">
<input type="hidden" name="onsigners[0][id]" value="your_software_id_3262">
<input type="hidden" name="onsigners[1][arrive]" value="2017-06-03">
<input type="hidden" name="onsigners[1][last_name]" value="Smith">
<input type="hidden" name="onsigners[1][first_name]" value="Peter">
<input type="hidden" name="onsigners[1][dob]" value="1968-06-15">
<input type="hidden" name="onsigners[1][nationality]" value="DK">
<input type="hidden" name="onsigners[1][gender]" value="M">
<input type="hidden" name="onsigners[1][doc_country]" value="DK">
<input type="hidden" name="onsigners[1][doc_number]" value="DK3672643">
<input type="hidden" name="onsigners[1][doc_expire]" value="2020-12-02">
<input type="hidden" name="onsigners[1][home_airport]" value="CPH">
<input type="hidden" name="onsigners[1][email]" value="smith@gmail.com">
<input type="hidden" name="onsigners[0][id]" value="your_software_id_2345">
<input type="hidden" name="offsigners[0][arrive]" value="2017-06-03">
<input type="hidden" name="offsigners[0][last_name]" value="Petrov">
<input type="hidden" name="offsigners[0][first_name]" value="Sergey">
<input type="hidden" name="offsigners[0][dob]" value="1965-11-22">
<input type="hidden" name="offsigners[0][nationality]" value="RU">
<input type="hidden" name="offsigners[0][gender]" value="M">
<input type="hidden" name="offsigners[0][doc_country]" value="RU">
<input type="hidden" name="offsigners[0][doc_number]" value="RU3627362332">
<input type="hidden" name="offsigners[0][doc_expire]" value="2019-08-11">
<input type="hidden" name="offsigners[0][home_airport]" value="MOW">
<input type="hidden" name="offsigners[0][email]" value="petrov@mail.ru">
<input type="hidden" name="onsigners[0][id]" value="your_software_id_892">
<input type="submit" value="Search flights">
</form>
You may use POST requests to send your users from your crewing system straight to search results in C Teleport. In this case C Teleport has no access to your crewing system and you maintain the highest level of security. However it decreases flexibility because suggestion of seamen by name is not possible.
Here is the desired workflow:
When a user lands on C Teleport webpage, he has to be authorised. If the user was previously authorised he seamlessly proceeds to the search results page.
If your crewing system is browser-based, we recommend using <form method="POST"> with hidden fields pre-filled with the required data.
Data format is the same as in crew change by date.
In this case the user will be leaving your crewing software and go to C Teleport. User will land straight on search results page. After finalising bookings user will have to go back to your crewing software. You may also chose to send the booked tickets back to your crewing software. In this case you need to have additional syncing integration.
3. Reverse integration
Sample payload
{
"actions":
[
{
"action": "confirmed",
"timestamp": 1514925900,
"user": "email@yourcompany.com"
},
{
"action": "cancelled",
"timestamp": 1514925950,
"user": "email@yourcompany.com" // email or "c teleport bot" keyword
}
],
"passenger": {
"last_name": "Timze",
"first_name": "Oskars",
"id": "crew-2323" // Id received from your software through integrations in article 2
},
"durations": [455],
"segments": [
{
"carrier": "KL",
"flight_number": "3092",
"origin": "RIX",
"origin_name": "Riga",
"destination": "AMS",
"destination_name": "Amsterdam",
"departure_date": "2018-01-02",
"departure_time": "16:25",
"connecting": true,
"arrival_date": "2018-01-02",
"arrival_time": "17:50",
"cabin_class": "Economy"
},
{
"carrier": "KL",
"flight_number": "1097",
"origin": "AMS",
"origin_name": "Amsterdam",
"destination": "MAN",
"destination_name": "Manchester",
"departure_date": "2018-01-02",
"departure_time": "21:45",
"arrival_date": "2018-01-02",
"arrival_time": "22:00",
"destination_terminal": "3",
"connecting": false,
"cabin_class": "Economy"
}
]
,
"baggage": {
"RIX-MAN": {
"checked": {
"pcs": 2,
"weight": 23,
"url": "MYTRIPANDMORE.COM/BAGGAGEDETAILSKL.BAGG"
}
}
},
"tickets": ["0745267507710"], // Can be multiple tickets
"id": "285e3b89ee3846a5a6e035d4794939a8",
"locator": "C-DRF2P8",
"terms": {
"fare_type": "marine",
"splitting": false,
"conditions": "refundable"
},
"metadata": {
"vessel_name": "WIND INNOVATION",
"vessel_flag": "GB",
"crew_change_member": "onsigner",
"crew_change_airport": "MAN",
"crew_change_date": "2018-01-02"
},
"state": "issued", // values: confirmed / issued / cancelled
"price": {
"total": 463.98,
"ccy": "EUR"
},
"created_at": 1513865074,
"created_by": {
"name": "Adam Smith",
"email": "smitrh@company.com"
},
}
When a user performs any action with the booking, C Teleport can provide this data back to your crewing system. When a user books a flight, your software will know the itinerary and price. When a user cancels a flight, your software will show that there is no booking anymore. This way your crewing software will remain in sync with C Teleport.
You can chose between pushing or pulling approach. With pushing approach you will have to develop API endpoints, where C Teleport will push data on bookings to your system in real time. If you don't want to develop endpoint for some reason, you may chose to pull this data from C Teleport API endpoints.
You will be notified of all states of your booking and corresponding ticket(s).
Here are the states that we deliver to your system by default.
Description of payload
Payload sent with push/pull request will consist of a set of actions performed by user or system and a complete snapshot of the booking after this action.
| Section | Purpose |
|---|---|
| actions | Array of actions related to your booking. There will be always only 1 action if you are using pushing approach. There can be multiple actions if you are pulling, because we will accumulate actions between current and the previous pull call. |
| passenger | Passenger data for double-checking together with the passenger's ID, which we received from your software through integrations in article 2. |
| durations | Durations of all flights (segments) in the booking in minutes. |
| segments | Detailed information on each flight (segment) in the booking. |
| baggage | Baggage allowances. |
| tickets | List of issued tickets. Can be empty if tickets are not issue yet. |
| id | ID used to identify the booking in C Teleport. Can be used to build URLs to C Teleport. For example, to open a booking screen. |
| locator | User-friendly identifier of the booking. Used by support team to identify and find bookings. |
| terms | Contains data on terms of the ticket: is it marine or public ticket, is it single or split-ticket (consists of two reservations). |
| metadata | Data on crew change and direction of the flight: off- or on-signing. |
| state | Current state of the booking: confirmed, issued, refund_pending, cancelled. |
| price | Data on price and currency. |
| created_at | Timestamp of creating the booking. |
| created_by | Details on the user, who created the booking |
Option 3.1. C Teleport pushes data to you
Sample request
POST https://yourcompany.com/api/sync_flights
Under this scenario C Teleport will be pushing payload as described above to your API endpoint. You have to develop the API endpoint and process the received data.
Please tell us the endpoint address as well as security information.
As soon as a user performs an action, which changes states of a booking or a ticket, C Teleport will call your API endpoint. You will have to process received payload.
Option 3.2. You pull data from C Teleport
Sample request
GET https://integrations.cteleport.com/pull/bookings
Header: X-Api-Key: [your API key]
When you want to maintain top level of security, you may pull the data about flights from C Teleport instead of pushing it. This way your system remains completely closed, but you still can sync the flights data.
Under this scenario you will call our API endpoint https://integrations.cteleport.com/pull/bookings. This endpoint will accumulate all changes that you didn't collect since your last call. Therefore you will be receiving an array of bookings with arrays of actions performed with the bookings.
Please mind that unlike PUSH, this method will not provide real-time synchronisation between C Teleport and your system.
Other methods for data exchange
While we strongly recommend HTTP GET/POST data exchange methods with JSON payload, we also understand that some systems may not support it. Therefore we accept virtually any other methods of communication, incl.:
- non JSON file types
- XML, SOAP
- CSV
- YAML
- others
- Non HTTP data exchange
- FTP file transfer
- SSL file transfer
- E-mail file transfer
Please remember that we can develop a secure and stable webservice for you even if your current software does not support it. Please contact us if you need help.
FAQ
How long does it take to integrate?
From our experience development itself takes just a few hours depending on complexity of your database.
What if we are missing some data?
Crew managers will always have an option to fill missing data while booking
Our airports are not stored in 3-letter format. What shall we do?
We have experience of transforming string names of airports to 3-letter codes. The trick is that shipping companies work with a limited number of nationalities and therefore limited number of home airports.
What if we don't store home airports?
It is highly recommended to contact your crew and collect this data. If you are completely missing data on home airports we have smart algorithms, which "guess" the most suitable airport for seamen.
If you don't have 3-letter codes, please send us a list of unique airport names + counts of the airports. We will implement the transformation on our side.
What if we don't have 2-letter codes of countries?
If you have an id - country name database, please provide it to us.
In case you store country names in plain text format, without IDs, we may implement data transformation on our side.
What is the format for seaman data?
Sample seaman's data in JSON
{
"last_name": "Smithsen",
"first_name": "John",
"dob": "1978-12-03", // YYYY-MM-DD format
"nationality": "GB", // 2 letters
"gender": "M",
"doc_country": "GB", // 2 letters
"doc_number": "UK36276372323",
"doc_expire": "2019-04-22", // YYYY-MM-DD format
"home_airport": "LON", // 3 letters. Required for full crew change data
"email": "smithsen@gmail.com", // Optional
"arrive": "2017-06-03" // Optional.
"id": "231", // Optional. Required for syncing flights
}
We recommend the following format for seamen's data in JSON. You may chose to use your own format, but this format will provide faster implementation.
| Parameter | Format | Description |
|---|---|---|
| last_name | string | Last name |
| first_name | string | First name |
| dob | YYYY-MM-DD | Date of birth |
| nationality | 2 letters | Nationality |
| gender | M or F | Gender |
| doc_country | 2 letters | Passport issuance country |
| doc_number | string | Passport number |
| doc_expire | YYYY-MM-DD | Passport expiry date |
| home_airport | 3 letters | Home airport of the seaman |
| string | Optional. Email of the seaman | |
| id | string | Optional. ID number of the seamen for backwards synchronisation |
How to test an API?
We recommend using Postman to test how APIs respond. You can check format as well as speed of response there.
Is this secure?
We recommend communications over HTTPS, which will be protected by the SSL certificate. It is virtually impossible to break it. Ask us if you have questions about security.
In addition, C Teleport is GDPR compliant. Therefore, you may request us to delete all data should you decide to do so.