Provision a seat

Restricted — requires a sponsorship program. See the Sponsorship API overview for access and auth.

POST /v1/partners/sponsorships
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/json

Auto-provisions one crew member into a sponsored Premium seat in a single call (just-in-time). DSS creates or reuses the account, attaches the vessel by IMO, turns on Premium, and starts billing the seat to you. The member is active on success.

Request body

Field	Type	Required	Notes
`email`	string	Yes	Crew member’s email. Normalised (trimmed, lower-cased) and used as the idempotency key.
`first_name`	string	Yes	Given name for the account.
`last_name`	string	Yes	Family name for the account.
`position`	string	Yes	Crew rank/role, e.g. `Chief Stewardess`.
`vessel_imo`	string	No	Exactly 7 digits (`^\d{7}$`) when present. See Members with no vessel.
`phone`	string	No	E.164, e.g. `+447700900123`.
`vessel_name`	string	No	Display name; helps when the IMO is new to DSS.
`join_date`	string (date-time)	No	ISO 8601. When the member joined the vessel.
`external_ref`	string	No	Your own opaque reference. Echoed back on the roster for reconciliation.

{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "position": "Chief Stewardess",
  "vessel_imo": "9074729",
  "vessel_name": "MY Example",
  "phone": "+447700900123",
  "join_date": "2026-07-01T00:00:00Z",
  "external_ref": "ref-0042"
}

Response

201 Created when a new seat is provisioned; 200 OK on an idempotent replay (an open seat already existed for this email — see below).

Field	Type	Notes
`sponsorship_id`	string	The seat id. Use it with the get and remove endpoints.
`status`	string	Seat lifecycle status — typically `active`.
`vessel_resolved`	boolean	`false` when the IMO didn’t match a known vessel. This is a soft failure: the seat is still created and the member still gets Premium; tracking attaches once the vessel is resolved.
`expires_at`	string \| null	The member’s sponsored term end (`activated_at` + the program term).

{
  "sponsorship_id": "665f00000000000000000042",
  "status": "active",
  "vessel_resolved": true,
  "expires_at": "2027-07-24T09:00:00Z"
}

vessel_resolved: false is not an error. A 7-digit IMO that DSS hasn’t seen yet still yields a provisioned, Premium seat. Pass vessel_name to help, and DSS resolves and back-fills tracking asynchronously. Poll the seat on the roster if you want to confirm resolution.

Idempotency

Provisioning is idempotent per email within your program:

If the email already holds an open seat (active), the call returns that existing seat with 200 and does not create a second seat or a second bill.
Otherwise a new seat is created and returned with 201.

You may also send an optional Idempotency-Key header for your own tracing/retry safety:

Idempotency-Key: 5f3c...your-uuid...

The header is accepted for convenience, but the email is the primary idempotency key — an open seat for the same email is never duplicated, regardless of the header value.

Members with no vessel

vessel_imo is optional. A member between jobs, working shoreside, or on a hull with no IMO still gets their account and Premium — provision them without it:

{
  "email": "alex@example.com",
  "first_name": "Alex",
  "last_name": "Crew",
  "position": "Deckhand"
}

The seat comes back with vessel_resolved: false and no vessel_id. Everything else works normally: the member is Premium immediately and is billed to you from that moment. When they join a vessel, re-submit the same email with the IMO. That is treated as a vessel move — it attaches the vessel and starts tracking, and does not create a second seat or a second charge.

vessel_resolved: false also comes back when an IMO is supplied that we cannot validate. We do not create a placeholder vessel for an IMO we could not confirm, because tracking a member against a hull that may not exist is worse than reporting the vessel as unresolved. Re-submit once the IMO is correct.

Omitting vessel_imo is not the same as sending a wrong one. A malformed value is rejected with 422 rather than ignored — silently dropping a typo’d IMO would leave the member with no vessel and no signal that anything went wrong.

Errors

Status	`type`	When
400 / 422	`invalid_request`	Missing/invalid field, e.g. `vessel_imo` present but not exactly 7 digits.
401	`invalid_token`	Missing or bad Basic credentials.
403	`insufficient_scope`	The partner account is suspended.
409	`email_already_premium`	The email already self-pays for Premium — nothing to sponsor.
409	`sponsorship_cap_reached`	The program’s seat cap is full. (Programs may be uncapped.)

Get started

Webhooks

Errors

Partner sponsorships (restricted)

Resources

Request body

Response

Idempotency

Members with no vessel

Errors

​Request body

​Response

​Idempotency

​Members with no vessel

​Errors

​Related

Request body

Response

Idempotency

Members with no vessel

Errors

Related