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

Attaches an existing DSS member to a sponsored Premium seat. DSS does not create a new account here. If the email is unknown, the call returns account_requires_signup (409) with signup_url — send the member through normal signup, then Connect. When the account already exists: attaches the vessel by IMO (optional), 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 who already has a DSS account but is between jobs, shoreside, or on a hull with no IMO still gets Premium — provision them without an IMO:

{
  "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	`account_requires_signup`	No DSS account yet — redirect to `signup_url`. Do not create one yourself.
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