tech
news
managers

Early access: Crewdentials API & WebHooks!

James Benns on May 12, 2022

Introducing cAPItan, our all new API which is now available by request to anyone with a Crewdentials for managers account! Here's how it works:

Authorisation

Set an Authorization header with the following information separated by a single space:

  • Caller type ('API')
  • Access key ID (contact us to receive your access key ID)
  • Secret access key (contact us to receive your secret access key)

Here's an example:

Authorization: API {access_key_id} {secret_access_key}

Create and invite a seafarer

Programatically add users to your manager account, and we'll take care of inviting them and creating a profile! We will respond with their ID, which you can use to retrieve the data at any time.

Request:

POST https://crewdentials.app/api/crew

{ "firstName": "Jack", "lastName": "Sparrow", "email": "jack@crewdentials.com" }

Response:

{ "crewDocId": "alDcx5vfcW123Fv8" }

Retrieve a crew member by ID

Programatically add users to your manager account, and we'll take care of inviting them and creating a profile! We will respond with their ID, which you can use to retrieve the data at any time.

Request:

GET https://crewdentials.app/api/crew/{crew_ID}

Response:

{ "invited": "2022-05-04T12:43:46.298Z", "firstName": "Jack", "emails": [ "jack@crewdentials.com" ], "lastName": "Sparrow", "id": "Avf8NKPTFxrRBYetrO07", ...lots of other useful data! }

Search your crew list

Search your crew list by email or last name!

Request:

GET https://crewdentials.app/api/crew?email=jack@crewdentials.com

GET https://crewdentials.app/api/crew?lastName=Sparrow

Response:

{ "results": [ { "firstName": "Jack", "emails": [ "jack@crewdentials.com" ], "lastName": "Sparrow", "id": "Avf8NKPTFxrRBYetrO07", ...lots of other useful data! } ] }

Contracts

Similar functionality is available for contracts. Contracts require only a role and a crewId but can take a vesselId and an employerId, as well as a whole host of other contract specific fields. Explore the API at the following endpoints: (Full documentation coming soon!)

Create:

POST https://crewdentials.app/api/contracts

Update:

PATCH https://crewdentials.app/api/contracts/{contract_id}

Get by ID:

GET https://crewdentials.app/api/contracts/{contract_id}

Search by crewId, vesselId or role:

GET https://crewdentials.app/api/contracts?vesselId={vessel_id}

Receive updates with WebHooks

Let us know your webhook for the crew-updated event and you will be notified of any changes to crew personal details on your account. If you would like to receive updates any time a crew member alters his/her profile through Crewdentials for Crew, turn on 'Auto-sync crew data' in your settings page.

We will issue you an access key and secret which we use to sign every request so you can be sure it originated from us and was not tampered with. You will find this signature in the x-crewdentials-signature header - don't forget to check it before you use trust the data inside.

POST {your_webhook}

const signature = crypto .createHmac("SHA256", {crewdentials_secret_access_key}) .update(event.body) .digest("hex"); if (signature === event.headers["x-crewdentials-signature"]) { // trusted! }

The body of the request will contain the crew member's whole record as it now stands, including the changes.

{ "crew": { "firstName": "Jack", "emails": [ "jack@crewdentials.com" ], "lastName": "Sparrow", "id": "Avf8NKPTFxrRBYetrO07", ...lots of other useful data! } }

Watch this space!

Keep an eye out for more updates as we expand our API and add more events to our webhooks over the coming weeks.

We look forward to hearing from you if you have particular functionality you would like to see exposed, or if you want to get set up with your integration!