CaptnBoat public API documentation

The Capt'n Boat public API allows you to transmit the creation of a need to the Capt'n Boat sales team

For this you need to

  • Create a boat
  • Create an ad
  • Create a Job
  • Fill in the billing information of your customer

The sales team will then contact your client to finalize the reservation of your Sailor (Skipper / Hostess ... ) and will send him, payment link, invoice and contract by mail.

Objectives of the API

The objective of the CaptnBoat public API is to open certain functionalities of the platform to external users to allow them to publish CaptnBoat ads directly from their digital infrastructure. In particular, this API allows to:

  • Register the external user's vessels
  • Create an ad for this vessel. An ad corresponds to a given mission for this vessel, and can include several positions to be filled
  • Create a job description for a mission
  • Cancel a request.
  • Retrieve the contact information of the found sailor.

The API is not designed to manage the ships and announcements published. This functionality is made possible by the CaptnBoat user interface, through which all boats, missions and vacancies can be consulted/administered.

Technical implementation

The external API of CaptnBoat is a GraphQL API. Its access is limited to users with a connection token, provided on request by Captnboat.

In this documentation, all the available queries are detailed and illustrated by a simple example. For more details on the technical implementation of this API, please contact the CaptnBoat team at the following address: api-ext@captnboat.com

Each connection to the external API must be made with the authentication token, passed in the x-api-key header.

Detail of available requests

Registering a vessel

To register a vessel, all the following information about a vessel is passed to the API:

  • its name
  • the name of the builder
  • the model name
  • its size
  • its propulsion type (sail or engine)
  • its hull type (monohull or multihull)
  • its flag ID (more details later to retrieve the list of flags)
  • its engine power if it is a motor vessel
  • its registration number
  • a list of photos (url list)
  • whether the boat has an autopilot or not

Following the registration of a vessel, the API sends in response the ID of the newly created vessel.

In case the same information is passed several times to register a vessel, it will not be recreated, the API will simply return the ID of the already registered vessel with similar info.

⚠️ Ships in the database are attached to a flag, the list of which includes over 200 entries. An API request is available to list the flags.

  1. List the flags.

    {
      listFlags {
        nodes {
          id
          name
        }
      }
    }

    Example of a request

    curl 'https://api-int.captnboat.com/opengraphql' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: 4dd092283af8df27dd2943333149b7f7' \
    -d '{"query":"{listFlags{nodes{id name}}}"}'

  2. Register a boat.

To register a vessel, the GraphQL API offers the mutation:

mutation CreateBoat {
  createBoat(
    input: {
      name: "testBoat3"
      flagId: "ef08f160-9858-464b-9e59-a93f94ad5260"
      boatPictures: ["http://mypictures.com/myboat.jpg"]
      boatType: MOTORBOAT
      builderName: "jo boats"
      enginePower: 10
      hullLength: 1.5
      hullType: MONOHULL
      modelName: "jo boat 1"
      registrationNumber: "registration"
      asAutopilot: true
    }
  ) {
    boat {
      id
    }
  }
}

In case the same information is passed several times, the boat will not be recreated, and the mutation will just return its ID

  • Payload

    name: String!

    flagId: UUID!

    boatPictures: [String]

    boatType: BoatTypeEnum! The accepted values are: : MOTORBOAT, SAILBOAT, MULTIHULL

    builderName: String!

    enginePower: Int!

    hullLength: Float!

    hullType: HullTypeEnum! The accepted values are: : MONOHULL, CATAMARAN, TRIMARAN

    modelName: String!

    registrationNumber: String

    asAutopilot: Boolean

  • Resultat

    {
      "data": {
        "createBoat": {
          "boat": {
            "id": "b408c93b-74a7-4d67-9fdd-a61f764e2284"
          }
        }
      }
    }

Create a job

In order to create a mission, information about the route and the ports of departure and arrival are required, as well as the id of a vessel. This mutation is therefore usually executed directly after the creation of a vessel, unless the id of the registered vessels are stored by the user. To create a mission, we dispose of the following mutation:

mutation CompleteAd {
  createCompleteAd(
    input: {
      adType: CHARTER
      boatId: "b408c93b-74a7-4d67-9fdd-a61f764e2284"
      startDate: "2022-06-01"
      endDate: "2022-06-15"
      spokenLanguage: ["245e9757-a9ab-4fd8-af33-f99498d5d3ef"]
      endHarborLattitude: 47.27991613225704
      endHarborLongitude: -2.1976906604134157
      startHarborLattitude: 47.27991613225704
      startHarborLongitude: -2.1976906604134157
      passengerNumber: 10
      description: "Une description"
      commercialActivity: false
    }
  ) {
    ad {
      id
    }
  }
}

  • Payload

    startDate: Datetime!

    boatId: UUID!

    endDate: Datetime!

    startHarborLattitude: Float!

    startHarborLongitude: Float!

    endHarborLattitude: Float!

    endHarborLongitude: Float!

    adType: AdTypeEnum! The accepted values are:: CHARTER ou COACHING

    passengerNumber: integer

    passengerNumber: Int

    description: String

    commercialActivity: Boolean f private client no, if professional yes.

    spokenLanguage: [UUID]!

The possible values for spokenLanguages are listed in the following query::

{
  languages {
    nodes {
      id
      name
    }
  }
}

  • Result

    {
      "data": {
        "createCompleteAd": {
          "ad": {
            "id": "2c2bf016-5604-4e71-bf81-3a1e7399ee9d"
          }
        }
      }
    }

Create a job offer

To get an estimation of a sailor's salary

query price {
  estimatedPrice(
    adType: DELIVERY
    endDate: "2024-08-15"
    endHarborLattitude: 47.27991613225704
    endHarborLongitude: -2.1976906604134157
    startHarborLattitude: 47.27991613225704
    startHarborLongitude: -2.1976906604134157
    hullLength: 1.5
    positionType: SKIPPER
    startDate: "2024-08-08"
  )
}
  • Payload

endDate: String!

startDate: String!

endHarborLattitude: Float!

endHarborLongitude: Float!

startHarborLattitude: Float!

startHarborLongitude: Float!

adType: AdTypeEnum!The accepted values are::CHARTER,SUPPORTetCOACHING``hullLength: Float!positionType: PositionEnum! The accepted values are:: SKIPPER, HOTESSE, MATELOT, SECOND, CHEF, MECANICIEN et CHEF_DE_QUART

hullLength: Float!

positionType: PositionEnum!The accepted values are::SKIPPER,HOTESSE,MATELOT,SECOND,CHEF,MECANICIENetCHEF_DE_QUART`

  • Results

    {
      "data": {
        "estimatePrice": {
          "cost": 2360
        }
      }
    }

To create a job offer, basic information about the profile being searched for, as well as billing information, is requested. The mission ID is also requested, so this migration is usually executed directly following the creation of a mission, unless the identification of the created missions is stored in the database. To create a job offer, we have the following mutation:

mutation CompleteJob {
  createCompleteJob(
    input: {
      billingDateOfBirth: "2000-01-01"
      billingEmail: "`billing@myco.com`"
      billingFirstname: "jo"
      billingLanguage: "fr"
      billingLastname: "durand"
      billingPhoneNumber: "1234567890"
      billingRegistrationNumber: "ag-y78hn5"
      billingSiret: "1234567890"
      positionType: SKIPPER
      price: 1500
      adId: "20ca3ae7-a1c0-4bba-984f-0a9c952f7207"
      billingAdressFirstLine: "52 rue Truffaut"
      billingAdressZipCode: "75017"
      billingAdressCityName: "Paris"
      billingAdressCountry: "FR"
      lessor: ""
      referenceId: "12"
      reserved: "FAVOURITES"
    }
  ) {
    job {
      id
    }
  }
}
  • Payload

billingDateOfBirth: String!

billingEmail: String!

billingFirstname: String!

billingLanguage: String

billingLastname: String!

billingPhoneNumber: String!

billingRegistrationNumber: String!

billingSiret: String

positionType: PositionEnum! The accepted values are: SKIPPER, HOTESSE, MATELOT, SECOND, CHEF, MECANICIEN et CHEF_DE_QUART

price: Float!

adId: UUID!

billingAdressFirstLine: String!

billingAdressZipCode: String!

billingAdressCityName: String!

billingAdressCountry: String!

lessor : String

referenceId: String You can link a Capt'n Boat job request to your file by filling in this reference field in order to connect a file to a Capt'n Boat job request.

reserved : ReservedEnum The accepted values are: ALL, APPROVED, FAVOURITES, RESERVED,

  • Results

    {
      "data": {
        "createCompleteJob": {
          "job": {
            "id": "636301f5-6c31-4d20-88c6-4eb8ddd81382"
          }
        }
      }
    }

Annuler une demande

To cancel a job request you created, you need the job posting ID or the reference if you provided one during creation. The mutation is as follows:

mutation CancelJob {
  cancelJob(
    input: {
      reason: "DELAYED"
      jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
      referenceId: "12"
    }
  ) {
    job {
      id
    }
  }
}

  • Payload

    reason: String

    • "FOUND" : "I found a sailor through another channel."
    • "DELAYED" : "My need is postponed."
    • "NOT_FOUND" : "I can't find any matching profiles."
    • "ERROR" : "The ad contains errors."
    • "DUPLICATE" : "Duplicate"
    • "CONTACT" : "To be contacted by a salesperson"
    • "OTHER" : "Another reason"

    jobId: String

    referenceId: String

    Résultat

    {
      "data": {
        "cancelJob": {
          "job": {
            "id": "636301f5-6c31-4d20-88c6-4eb8ddd81382"
          }
        }
      }
    }

    Sailors' offers

You can find all the offers that have been made by the sailors. :

query offres {
  jobOffers(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    captnBoatProfil
    firstName
    isCaptnBoatApprooved
    isFavoris
    picture
    price
    travelFee
    urlSignature
  }
}

  • Payload

    picture: String

    firstName: String

    urlSignature: String

    price: Float

    travelFee: Float

    isFavoris: Boolean

    isCaptnBoatApprooved: Boolean

    captnBoatProfil: String

  • Résultat

    {
      "data": {
        "sailorContact": {
          "captnBoatProfil": "",
          "firstName": "",
          "isCaptnBoatApprooved": "",
          "isFavoris": "",
          "picture": "",
          "price": "",
          "travelFee": "",
          "urlSignature": "",
        }
      }
    }

Sailor contact

Once the service has been paid for by the client, you can retrieve the seafarer's contact information with the following query:

query contact {
  sailorContact(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    nodes {
      firstName
      birthCountry
      birthPlace
      birthday
      cityAdress
      civility
      countryAdress
      email
      lastName
      natinality
      phoneNumber
    }
  }
}

  • Payload firstName: String

    lastName: String

    email: String

    phoneNumber: String

    civility: CivilityEnum

    birthday: Datetime

    birthPlace: String

    birthCountry: String

    natinality: String

    countryAdress: String

    cityAdress: String

    price: Float

    travelFee: Float

    degree: String

    invoice: String

    contract: String

    Résultat

    {
      "data": {
        "sailorContact": {
          "firstName": "",
          "birthCountry": "",
          "birthPlace": "",
          "birthday": "",
          "cityAdress": "",
          "civility": "",
          "countryAdress": "",
          "email": "",
          "lastName": "",
          "natinality": "",
          "phoneNumber": ""
        }
      }
    }

Sailor's rating

Once the service has been completed and the client has left a comment for the mission :

query notation {
  jobNotation(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    notation
    comment
  }
}

  • Payload

    comment: String

    notation: String

  • Résultat

    {
      "data": {
        "sailorContact": {
          "notation": "",
          "comment": "",
        }
      }
    }

    For further enquiries, please contact us at api-ext@captnboat.com.