Account Management

With a CRM token (Onboarding) your service account creates and administers customer accounts. The id returned at creation is the key you pass to every CRM call that targets that user.

All calls on this page send Authorization: Bearer {crm_token}.

Create an account

Use v3 for new integrations

POST /api/v3/account is the recommended endpoint for all new integrations. It handles single, family, and business accounts in a single call via the type field and supports additional fields such as activation_date and vendor. The v1 create endpoints below are still supported but marked as deprecated.

POST /api/v3/account
Authorization: Bearer {crm_token}
Content-Type: application/json
X-API-Version: 2026-06-12

{
  "ssn": "19900101-1234",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "country_code": "SE",
  "lang_code": "SV",
  "plan_id": 1,
  "type": "SINGLE"
}

Response (201): the created account under data. Persist data.id as your {account_id}.

The type field controls which kind of account is created:

type	Creates
SINGLE (default)	Standard individual account
FAMILY	Family account — add members with POST /api/v1/account/{id}/member
BUSINESS	Business account — requires company_name, company_org_number, company_max_employee_count

SSN cannot be set or changed through CRM after creation

On the CRM (service-account) surface, ssn can only be provided at account creation (POST /api/v3/account). Every CRM update path — PUT/PATCH /api/v1/account/{account_id}, PUT /api/v2/account/{account_id}, and the targeted update routes — ignores ssn, so your backend cannot add or change it later with a CRM token. The SSN-monitoring routes below only toggle monitoring of an SSN that is already on the account; they do not add one.

If you do not provide the ssn at account creation, the only way to get it onto the account afterwards is to trigger the end-user electronic ID (eID) flow. The user authenticates with a trusted eID (BankID / MitID / FTN) and the verified SSN is written to their account. That flow uses the app token, not a CRM token — see Add an SSN via electronic ID. There is no CRM/service-account route to backfill an SSN.

Required and conditional fields

Field	Rule
ssn	Deployment-dependent. Required when your gateway runs with SSN_REQUIRED enabled (the default); on tenants where SSN collection is optional it may be omitted and backfilled later via the end-user eID flow. Confirm with your account manager.
email	Required when phone is omitted
phone	Required when email is omitted
plan_id	Required when your client uses plan-based billing — confirm with your account manager
company_name, company_org_number, company_max_employee_count	Required when type is BUSINESS
parent_id	Required when type is FAMILY and creating a sub-member directly (omit when creating the family root account)

SSN requirement varies by tenant

The API reference renders ssn as optional so both configurations validate, but most deployments require it at creation. Treat it as required unless your account manager confirms your tenant accepts accounts without an SSN.

Check uniqueness first

If you sync external identities, verify before creating to avoid duplicates:

POST /api/v1/account/check-attribute-for-uniqueness
Authorization: Bearer {crm_token}

{ "attribute": "email", "value": "john.doe@example.com" }

Family and multi-member plans add members and invite them:

POST /api/v1/account/{account_id}/member
POST /api/v1/account/{account_id}/invite
GET  /api/v1/account/{account_id}/members

Legacy v1 create endpoints (deprecated)

POST /api/v1/account (single/family) and POST /api/v1/account/business are still supported but deprecated. Migrate to POST /api/v3/account — the request body fields are identical; the only change is the URL and the addition of the type field to select account kind.

Look up accounts

GET /api/v1/accounts
GET /api/v1/account/{account_id}
GET /api/v1/account/external-id/{externalId}
GET /api/v1/account/get-id-by-ssn/{ssn}

Update an account

PUT   /api/v1/account/{account_id}
PATCH /api/v1/account/{account_id}

ssn cannot be updated

These update calls silently ignore an ssn field. The SSN is fixed at creation time — see SSN can only be set at creation.

Targeted changes have dedicated routes:

POST  /api/v1/account/{account_id}/change-email
PATCH /api/v1/account/{account_id}/delete-email
POST  /api/v1/account/{account_id}/change-supervisor
POST  /api/v1/account/{account_id}/password
POST  /api/v1/account/{account_id}/resend-confirm-email

delete-email: returns 409 CONFLICT if the email is the account's only contact method — ensure the account has a verified phone before removing the email.

change-supervisor: the ssn field is used to look up the incoming supervisor account. If ssn is omitted or doesn't match any account the API returns 404 (not 422).

resend-confirm-email: rate-limited — too many attempts in a short window returns 429. Passing an unknown {account_id} returns 404.

Activation

GET  /api/v1/account/{account_id}/activation-status
POST /api/v1/account/{account_id}/activate
POST /api/v1/account/{account_id}/deactivate

Plan changes

POST /api/v1/account/upgrade
POST /api/v1/account/downgrade

SSN monitoring

Enable or disable national-ID monitoring when the customer's plan includes it:

PATCH /api/v1/account/{account_id}/ssn-monitoring/activate
PATCH /api/v1/account/{account_id}/ssn-monitoring/deactivate

These routes only switch monitoring on or off for an SSN that was supplied when the account was created. They do not add an SSN to an account that doesn't have one.

Cooldown and error behaviour

• 48-hour cooldown: re-activating within 48 hours of a deactivation returns 422.
• Unknown account id: passing a non-existent {account_id} returns 500 (not 404) — the same behaviour as /deactivate.

Delete an account

DELETE /api/v1/account/{account_id}

v2 account operations

The v2 surface adds a refreshed update and member flow:

PUT  /api/v2/account/{account_id}
POST /api/v2/account/deactivate
POST /api/v2/account/member
POST /api/v2/account/member/{memberId}/invite
POST /api/v2/account/password
GET  /api/v2/accounts

v3 account operations

POST /api/v3/account is the unified account creation endpoint for new integrations, replacing the separate v1 single and business create routes:

POST /api/v3/account

Next step

Enrol monitored items for the account.