NAV Navbar
  • Introduction
  • 1. One seaman integration (required)
  • 2. Crew change integration
  • 3. Reverse integration
  • Other methods for data exchange
  • FAQ
  • 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:

    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?

    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:

    1. ~4 hours One seaman suggestion - Article 2.1
    2. ~4 hours Crew change data integration - Article 2.2
    3. ~20 hours Sending flight data back to the crewing software - Article 4
    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:

    Suggesting one seaman

    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.
    email 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: Seaman integration explained

    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.

    Crew change

    This is the desired workflow: Crew change integration explained

    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: HTTP Post demo

    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. Booking and ticke tlifecycle

    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
    

    Pushing synchronisation

    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]
    

    Pulling synchronisation

    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.:

    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
    email string Optional. Email of the seaman
    id string Optional. ID number of the seamen for backwards synchronisation

    How to test an API?

    Postman logo

    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.