Skip to Content
DocsOrganizationsMembers

Members & onboarding

A member is one person on your workforce roster. You add members three ways — one at a time in the portal, by CSV upload, or over the Organization API (addMembers()). Each member you add gets a stable member id vmem_… — store it against your own employee/user record; it’s your correlation key between your roster and Valyd.

How a member is invited

When you add someone, Valyd issues an invite. The method depends on the role, and you can force it with the invite option on add member(s):

inviteWhat happens
auto (default)Valyd picks the right link for the role. A workforce member (role: member) gets a face-activation link — they scan their face once to bind the membership to a real Valyd identity. An admin or developer gets an email claim link to join the console.
emailForce the email path — an email claim/activation link is sent.
faceForce the face-activation path — a face link is issued for the person to scan.

By default (notify: true) Valyd emails the link for you. Pass notify: false and each created member comes back with its own activation_link in the API response so you can deliver it yourself (your own email / SMS / in-app message). Note: activation_link is returned only for face invites — email/claim links are emailed, never handed back.

How a new member is notified

Adding a member (portal, CSV, or addMembers()) emails them their invite link — for the workforce, a face-activation link. They tap it, scan their face once, and their membership is bound to a real Valyd identity. Prefer to deliver it yourself? Pass notify: false and read each created member’s activation_link. Re-send anytime with resendMemberInvite(memberId). To know when someone finished, poll getMembers() and watch for status: "active".

Member lifecycle (status)

A membership moves through exactly four states:

statusMeaningBillable?
invitedCreated, no email sent yet (the notify: false path).No
link_sentActivation email sent, awaiting the person.No
activeFace-activated and bound to a Valyd identity.Yes — the only billable state
deactivatedRemoved from the workforce; app logins revoked, row kept.No

Only the active state is billable — a seat turns on the moment the member scans their face. See Pricing & billing.

One face = one member

A person’s face is their identity, so the same face can hold at most one active membership in your org. If someone is invited under a second email and scans the same face that is already an active member, Valyd does not create a duplicate seat: the activation is refused with already_member (“you’re already a member — sign in with your existing account”), and that second invite row is left deactivated with no valyd_id. A face therefore can never become two billed seats, and nobody is double-counted. The person keeps working through their existing membership. If a second email genuinely needs its own access under a different face, an admin reactivates the row and re-sends the invite.

Deactivate, remove, reactivate

  • Deactivate — deactivateMember(memberId) stops billing and revokes the member’s app logins, but keeps the row. Their Valyd identity is not deleted.
  • Remove — removeMember(memberId) is the same deactivation by default; pass { permanent: true } to delete the membership row outright, so the email can be re-invited cleanly. The person’s Valyd account is never deleted.
  • Reactivate — reactivateMember(memberId) restores a deactivated member to active if their Valyd identity still exists, or back to invited (they must re-activate by face) if it doesn’t.
  • Re-send an invite — if a member’s invite expired before they connected their Valyd ID, resendMemberInvite(memberId) issues a fresh face-activation link, superseding the old one. By default it emails the link and also returns it; pass notify: false to get the link back without emailing, so you can deliver it yourself (e.g. an in-app “Connect with Valyd” button that opens the link directly). It refuses for already-active or deactivated members.

None of these ever touch the person’s Valyd identity or their membership in any other organization. Only member-role people appear on the roster — use resolveMember({ valydId }) to check whether someone is a workforce member vs a developer/admin, or not in your org at all.

In the Developer Portal, the org owner/admin sees the full roster with each member’s status on the Organization → Members tab, and can re-send invites, deactivate/reactivate, or Remove a member outright (permanent, same as the API’s permanent: true).

Badges

Members (and any Valyd user who connects to your app) can hold badges — org-defined labels like “Background Check” or “Licensed Contractor”. Assign them to staff in Organization → Members, or grant them to users over the API with grantBadge(). Badges can also gate login to your private apps. See Badges for the full model (private vs public, expiry) and the badge API.

Account recovery

If a member is locked out of your app — they forgot the email/password they sign in with — you don’t delete the seat or its history. You start an identity-backed recovery: Valyd re-verifies the person (liveness + a face match against their enrolled face, plus a fresh document/KYC scan on the with_id variant) and returns a pass/fail to your Verify project’s webhook. startAccountRecovery returns a hosted recoveryUrl for you to deliver (pass deliverEmail:true to also have Valyd email it to the member’s on-file address). On a pass, your app lets them set a new password — Valyd stores and sets nothing.

await client.startAccountRecovery({ valydId: "valyd_…", variant: "with_id" });

See Account recovery for the full flow, the startAccountRecovery function, its responses, and the webhook contract.

Last updated on