Skip to main content

Creating Members

Connect a person in your system to a Member in a Gravity Rail Workspace. Create one synthetic Member first, then use CSV import for a batch.

A person's Account is global. Organizations contain Workspaces; membership and roles are assigned at each level.

An Account is global; Organization and Workspace memberships each have their own role.

The same Account can have different memberships and roles in different Organizations and Workspaces. This diagram shows a person's memberships; Agents are also Members, but do not require a person's Account.

For the product's import wizard and role settings, use Importing Members and Member roles. This guide covers API requests and identity reconciliation.

Before you begin​

For /create-signup, use an API key with members:write (or members:admin) that can reach the target Workspace. If the request also sends Form records in data, the key needs records:write (or records:admin) as well; without it the request is refused with a 403 and nothing is written. A workspace API key works: its creator must be a Member of that Workspace whose role already grants those scopes. Existing keys with org:admin are still accepted for both.

Signup reconciles identity. A request that matches an existing Member can update it, so keep the key as carefully as any key that can edit Members. Declare member.matchKeys to control which submitted identifiers may decide which person a write is about. Only the listed identifiers are tried, in order, and every other identifier is data. A contact value you do not declare that another Member or Account already holds is not written onto that Member; it is kept as a non-primary contact point and reported in warnings (see Declare match keys). Choose the key using Authentication. Store it in an environment variable or secrets manager.

Use synthetic data while developing. Before sending patient information, meet the PHI requirements, including a signed BAA and confirmed workspace configuration.

Create a Member​

Set GRAVITYRAIL_API_KEY and GRAVITYRAIL_WORKSPACE_UUID, then send:

curl --fail-with-body --request POST \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/create-signup" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"member": {
"email": "integration-test@example.com",
"name": "Integration Test",
"externalId": "integration-test-001"
}
}'

Provide at least one of email, phone, or externalId. Use externalId for your system's stable identifier. To select a role explicitly, supply member.role with an existing non-admin role name; signup cannot assign an admin role, and choosing any role other than the Workspace default needs member_roles:admin on the key — a members:write-only key gets a 403 for it. Omit member.role to use the default.

Declare match keys​

By default, signup decides which Member a write is about by trying the identifiers you send in this order: externalId, then email, then phone. When that matches an existing Member, signup treats you as a trusted source and may update the matched Member's contact details. You do not need to send anything extra to get this behaviour — it is what a request without matchKeys does. Under this default, every submitted identifier can decide the match, so a contact value that belongs to someone else must be left out of the request; if you cannot leave it out, declare a match key that is that person's own.

Pass member.matchKeys when you know which identifier is authoritative, or when the default order is not what you mean. The array overrides both the list of identifiers that may match and the order they are tried in. Its values are external_id, email, and phone (snake_case), and only the listed identifiers may match an existing Member or select an Account; every other identifier you send is data.

curl --fail-with-body --request POST \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/create-signup" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"member": {
"email": "integration-test@example.com",
"name": "Integration Test",
"externalId": "integration-test-001",
"matchKeys": ["external_id"]
}
}'

This request matches only the Member whose external id is integration-test-001, or creates one when that id is new. It cannot land on a different Member because of the email address. A longer array is a fallback order you chose, so its order matters: the first key that matches decides the person. When you have no external id for the person, declare ["email"] or ["phone"] instead — but only when that address or number belongs to that person alone. A declared key is your assertion that this identifier identifies that person, so declaring a shared or household contact value would match the person who holds it and write your patient's details onto their Member.

An empty array, or no matchKeys field at all, means the default; an empty array is treated exactly like an omitted one, so an integration that builds the list dynamically keeps working. A value outside the three listed returns 400 and writes nothing.

The following protections apply only when you send a non-empty matchKeys array. If you send no field, or an empty array, signup keeps the default behaviour and writes the submitted contact values as before:

  • When you send a non-empty matchKeys, a submitted email or phone that is not one of those keys and that another Member or Account holds is kept as a shared, non-primary contact point and reported as member_contact_field_shared in warnings; it never becomes the Member's primary contact and never becomes an Account credential. Under the default that value can decide the match and be written to the holder, which is why a shared value must be left out of the request or the caller must declare a key that belongs to that person.
  • A non-declared externalId is data like the rest, but if another Member already holds it the write is refused with 409, because an external id has no shared form.
  • Signup can answer with no login identity. When no submitted contact value could become an Account credential (all were set aside, or the request carried only an externalId under a declared key and that id matched no Account), or it matched a Member that has no Account, the response has account: null and token: "" with a member_login_identity_not_created warning. The Member exists; link it to an Account later by invitation. A role that requires an Account is refused with 409.

Read the response​

Check member.id and wasCreated. wasCreated describes the Member: true when signup created a new Member, false when it matched an existing one. It does not say whether an Account was created or reused. Keep the Member ID for subsequent requests.

Then read the rest of the response before using it:

  • account may be null and token may be "". That is a successful account-less signup: the Member has no login identity yet.
  • warnings may contain entries. Read each entry's code as an opaque string and branch on the codes you know. member_contact_field_shared reports a value kept as a non-primary contact point. member_login_identity_not_created explains a missing Account and token. The Signup API reference documents every code and its shape. A warning is a soft failure for the field or login identity it names; the rest of the request succeeded, and correcting the payload at the source is the durable fix.
  • A non-empty token is a credential. Keep it on your server and never put it in a browser URL or storage. Provisioning does not complete browser sign-in; use the normal Site sign-in flow for the next step.

Open Members in the Workspace to verify the result.

Do not log the response body, contact values, Form values, or returned tokens. Use IDs when reporting an error and follow Error handling.

Preview a CSV import​

A Member import requires members:admin and a valid role ID for newly created Members. Obtain the role ID from the Member Roles API. The signup request's members:write key check and the import request's members:admin requirement are separate contracts.

Save a synthetic members.csv:

email,name,external_id
integration-test@example.com,Integration Test,integration-test-001
second-test@example.com,Second Test,integration-test-002

Set GRAVITYRAIL_NEW_MEMBER_ROLE_ID to the selected role ID. Preview the file before writing:

curl --fail-with-body --request POST \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/members/import/preview?new_member_role_id=${GRAVITYRAIL_NEW_MEMBER_ROLE_ID}" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--form "file=@members.csv"

Review the create, update, unchanged, conflict, skipped, and error counts. Resolve identity conflicts before importing. A row whose contact values disagree with the matched Account needs an explicit resolution; do not select overwrite as a substitute for reviewing the match.

Start and verify the import​

Submit the reviewed file as a durable import:

curl --fail-with-body --no-buffer --request POST \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/members/import/runs?new_member_role_id=${GRAVITYRAIL_NEW_MEMBER_ROLE_ID}" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--form "file=@members.csv"

The response is an SSE stream with import_run, import_item, and done events. Keep the run ID. If the connection closes, find its summary with GET /members/import/runs, and retrieve row outcomes with GET /members/import/runs/{run_id}/items; a disconnected stream does not cancel the import. See the Members API for event and resolution formats.

Check the final created, updated, skipped, and failed outcomes. Correct rejected rows and preview them again before resubmitting.

Matching an exported Member​

When re-importing a Gravity Rail Member export, preserve its id or uuid and contact/external_id columns. A numeric ID is local to its Workspace: use an export from the same Workspace. Its row must corroborate that ID with an existing contact or external identifier, without conflicting values. An unrecognized or conflicting explicit key fails the row rather than updating a different Member. A matching Workspace Member UUID does not require the same corroboration.

CSV email matching is case-insensitive. Ambiguous matches fail rather than selecting an arbitrary Member. Use the preview and row outcomes to resolve them.

Update through your external identifier​

Once your Member exists, a synchronization job can address it without persisting its numeric ID:

curl --fail-with-body --request PUT \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/members/by-external-id/integration-test-001" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"description": "Synthetic integration test"}'

The external ID must identify a Member in the target Workspace; an unknown ID returns 404. Use the Members API for update permissions, labels, notification preferences, archive operations, and complete schemas. Use Importing Data to synchronize that Member's Form records.

Turn SMS off when your system deactivates a Member​

When a person becomes inactive in your system, send notifySms: false with smsDisabledReason: "upstream_deactivation". Gravity Rail stops SMS notifications for that Member and records why and when:

curl --fail-with-body --request PUT \
"https://api.gravityrail.com/api/v2/w/${GRAVITYRAIL_WORKSPACE_UUID}/members/by-external-id/integration-test-001" \
--header "Authorization: Bearer ${GRAVITYRAIL_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"notifySms": false, "smsDisabledReason": "upstream_deactivation"}'

When the person is active again, send {"notifySms": true}. That turns SMS back on and clears the reason and the time. The same fields work on PUT /members/{member_id}, on POST /members and on each item of a bulk member request.

  • On a request, smsDisabledReason is one of upstream_deactivation, manual, other or crm_opt_out. It is valid only with notifySms: false; other combinations return 422.
  • A response can also show default. It is internal and cannot be sent: it means the preference was never chosen, so SMS is off only because no preference was given. A background check later turns SMS on for such a Member once its phone is confirmed textable and no refusal is on record; sending notifySms: false records manual and ends that.
  • A new Member created without notifySms that has a phone number gets SMS turned on, with no reason. A new Member created with notifySms: false and no reason records manual. A new Member created without notifySms, whose SMS resolves off (for example, it has no phone number), records default.
  • On an existing Member, notifySms: false without a reason records manual when SMS is on, or off with no reason or with default. When SMS is already off for a specific reason (manual, upstream_deactivation, other or crm_opt_out), it keeps that reason and its time.
  • Sending the same reason again keeps the original smsDisabledAt, so a repeated sync does not move the date. Sending a different reason while SMS is off replaces the reason and sets a new smsDisabledAt.
  • The Member response carries smsDisabledReason and smsDisabledAt. Both are null while SMS is on.
  • An SMS STOP from the person is a separate opt-out record. It sets no reason here, and notifySms: true does not override it: Gravity Rail still does not text a person who sent STOP until they send START.
  • A START from the person turns SMS back on, whatever the reason was, and clears the reason and the time.

In the app, filter Members by SMS disabled reason or SMS disabled at.