Skip to main content
POST
Create a group

Authorizations

Authorization
string
header
required

Partner API key. psk_test_<32 hex> for test mode, psk_live_<32 hex> for live mode. Keys are stored hashed and cannot be recovered; store them in your secrets manager on issue.

Headers

Idempotency-Key
string

Any unique string (UUIDs work well). Replaying the same key within 24 hours returns the stored response instead of re-executing the request.

Maximum string length: 255

Body

application/json
companyName
string
required
Example:

"Acme Inc"

domain
string
required

Primary company domain. One enrolled group per domain per mode.

Example:

"acme.com"

externalId
string

Your internal employer ID. Echoed back on the group and useful for reconciliation.

Example:

"co_4821"

Example:

"Acme Incorporated"

ein
string
Example:

"94-2404110"

address
object
contact
object
currentCoverage
object

The employer's coverage today. pepmCents is used as the savings baseline when quoting unless overridden per-quote.

Response

Group created.

id
string
required
Example:

"grp_8c2f41d09a3e"

mode
enum<string>
required
Available options:
test,
live
status
enum<string>
required

Lifecycle: created -> census_received -> quoted -> enrolled -> active (active = company flipped to prod by Prescience).

Available options:
created,
census_received,
quoted,
enrolled,
active
companyName
string
required
Example:

"Acme Inc"

domain
string
required
Example:

"acme.com"

censusMemberCount
integer
required
Example:

12

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
externalId
string | null

Your internal employer ID.

Example:

"co_4821"

address
object
contact
object
currentCoverage
object

The employer's coverage today. pepmCents is used as the savings baseline when quoting unless overridden per-quote.

companyState
enum<string> | null

null until enrolled, then sandbox, then prod once Prescience activates the group.

Available options:
sandbox,
prod,
null