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!