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.
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 asmember_contact_field_sharedinwarnings; 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
externalIdis data like the rest, but if another Member already holds it the write is refused with409, 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
externalIdunder a declared key and that id matched no Account), or it matched a Member that has no Account, the response hasaccount: nullandtoken: ""with amember_login_identity_not_createdwarning. The Member exists; link it to an Account later by invitation. A role that requires an Account is refused with409.
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:
accountmay benullandtokenmay be"". That is a successful account-less signup: the Member has no login identity yet.warningsmay contain entries. Read each entry'scodeas an opaque string and branch on the codes you know.member_contact_field_sharedreports a value kept as a non-primary contact point.member_login_identity_not_createdexplains 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
tokenis 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,
smsDisabledReasonis one ofupstream_deactivation,manual,otherorcrm_opt_out. It is valid only withnotifySms: false; other combinations return422. - 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; sendingnotifySms: falserecordsmanualand ends that. - A new Member created without
notifySmsthat has a phone number gets SMS turned on, with no reason. A new Member created withnotifySms: falseand no reason recordsmanual. A new Member created withoutnotifySms, whose SMS resolves off (for example, it has no phone number), recordsdefault. - On an existing Member,
notifySms: falsewithout a reason recordsmanualwhen SMS is on, or off with no reason or withdefault. When SMS is already off for a specific reason (manual,upstream_deactivation,otherorcrm_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 newsmsDisabledAt. - The Member response carries
smsDisabledReasonandsmsDisabledAt. Both arenullwhile SMS is on. - An SMS STOP from the person is a separate opt-out record. It sets no reason
here, and
notifySms: truedoes 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.