{"id":"69ecef9a60bb8b34fce600a9","title":"Calling The Api","path":"how-to/technical-articles/2026-04-21-using-ramblers-salesforce-mock/calling-the-api","contentMarkdown":"# 21-Apr-2026 — Calling the API\n\n_____\n\nTwo endpoints are live, both implementing the day-one contract from [#209](https://github.com/nbarrett/ngx-ramblers/issues/209). Both require an `Authorization: Bearer ` header, and the tenant in the path must match the tenant the token is scoped to.\n\n[← Back to the overview](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-04-21-using-ramblers-salesforce-mock)\n\n## Try it in Swagger UI\n\nThe quickest way to pull data is the interactive API docs, no code required. Go to [`/docs`](https://salesforce-mock.ngx-ramblers.org.uk/docs), click **Authorize** in the top right, paste your token (without the `Bearer ` prefix), then expand either endpoint and click **Try it out**. [Swagger UI](https://swagger.io/tools/swagger-ui/) builds the request with the right headers and shows the response inline, so you can list a tenant's members or post a consent change straight from the browser.\n\n![](https://ngx-ramblers.org.uk/api/aws/s3/site-content/b13d3f2c-f50b-4e99-804c-b4c9941bc7eb.png)\n\n*Swagger UI at /docs: the day-one contract as an interactive console. Authorize once with your token, then expand list members or consent writeback and click Try it out to call it live.*\n\nThe same contract is published as a machine-readable [OpenAPI document](https://salesforce-mock.ngx-ramblers.org.uk/api/openapi.json) at `/api/openapi.json`, which you can feed to a client generator.\n\nIf you would rather script it or wire it into an integration, the curl recipes below hit those same two endpoints.\n\n## List members\n\nReturns every non-removed member in the tenant.\n\n```sh\nTOKEN='rsm_KT50_your-48-hex-token-here'\ncurl -sS \\\n -H \"Authorization: Bearer $TOKEN\" \\\n https://salesforce-mock.ngx-ramblers.org.uk/api/groups/KT50/members \\\n | jq .\n```\n\nThe response shape is `MemberListResponse` (full schema in the [OpenAPI document](https://salesforce-mock.ngx-ramblers.org.uk/api/openapi.json)):\n\n```json\n{\n \"totalCount\": 412,\n \"members\": [\n {\n \"membershipNumber\": 3300001,\n \"firstName\": \"Aoife\",\n \"lastName\": \"Doyle-Adams\",\n \"email\": \"aoife.doyle1@ngx-ramblers.org.uk\",\n \"consents\": { \"emailMarketingConsent\": true, ... },\n \"groupMemberships\": [ { \"groupCode\": \"KT50\", \"roles\": [\"walkLeader\"] } ],\n \"membershipExpiryDate\": \"2026-12-31\"\n }\n ]\n}\n```\n\nThe same path `/api/groups/{code}/members` is used for both group and area tenants today — the route accepts whichever 2-to-6-character code your token is scoped to. The `groupCode` segment name is a known wrinkle: a parallel `/api/areas/{code}/members` (or a renamed `/api/tenants/{code}/members`) is the obvious next step, but tracking ticket [ramblers-salesforce-mock#1](https://github.com/nbarrett/ramblers-salesforce-mock/issues/1) currently keeps both kinds on the single path so existing consumers don't have to switch URLs mid-integration.\n\n### Incremental sync — `?since=`\n\nPass an ISO-8601 timestamp to get only what's changed since then:\n\n```sh\ncurl -sS \\\n -H \"Authorization: Bearer $TOKEN\" \\\n \"https://salesforce-mock.ngx-ramblers.org.uk/api/groups/KT50/members?since=2026-04-01T00:00:00Z\" \\\n | jq .changes\n```\n\nThe response gains a `changes[]` array with three kinds of entry: `added`, `updated`, and `removed`. Soft-removed members (those that disappeared in a later upload) appear here with `removed`, which is how downstream syncs notice deletions without the mock having to keep dead rows in the main `members[]` array.\n\nIf `?since=` returns nothing new, check that your timestamp is earlier than the most recent ingest. Freshly ingested rows have `updatedAt` set to the ingest time; anything before that drops out of `changes[]`.\n\n### Include lapsed memberships — `?includeExpired=true`\n\nBy default the list excludes members whose membership expiry date is in the past. Add `?includeExpired=true` to get them too — useful for renewal-reminder workflows.\n\n## Writeback a consent change\n\nA single endpoint updates one or more consent flags for a specific member.\n\n```sh\ncurl -sS -X POST \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"emailMarketingConsent\": false,\n \"source\": \"ngx-ramblers\",\n \"timestamp\": \"2026-04-21T09:00:00Z\",\n \"reason\": \"unsubscribe-link\"\n }' \\\n https://salesforce-mock.ngx-ramblers.org.uk/api/members/3300001/consent \\\n | jq .\n```\n\nReturns a `ConsentUpdateResponse` with the updated flags and `success: true`. The change is also logged to a `consentEvents` collection, which is what an HQ-side audit would consult.\n\n| Field | Notes |\n|---|---|\n| `source` | Per the [#209 contract](https://github.com/nbarrett/ngx-ramblers/issues/209), valid values are `ngx-ramblers` or `mailman`. New consumers can be added to the enum if needed — open an issue. |\n| `timestamp` | ISO-8601. Used to break ties when two systems write competing values. |\n| `reason` | Optional free-form string for audit context. |\n| Consent flags | Any of `emailMarketingConsent`, `groupMarketingConsent`, `areaMarketingConsent`, `otherMarketingConsent` — provide only the ones you want to change. At least one must be present. The two xlsx-only flags (`postDirectMarketing`, `telephoneDirectMarketing`) are not writeable through this endpoint by design — the source of truth for those remains the Insight Hub upload. |\n\n## Common errors\n\n| Status / code | Meaning |\n|---|---|\n| **401 UNAUTHORIZED** | Token missing, malformed, revoked, or unknown. Check the `Authorization` header; generate a new token if you've lost the original. |\n| **401** with \"Token is not authorised for tenant X\" | You're calling `/api/groups/X/members` with a token generated for a different tenant. Tokens are scoped to one code only — use the right token, or generate one for the right tenant. |\n| **404 GROUP_NOT_FOUND** / **AREA_NOT_FOUND** | No tenant with that code exists. Create it first in the admin UI. |\n| **404 MEMBER_NOT_FOUND** (consent writeback) | No member with that `membershipNumber` exists in any tenant your token can reach. |\n| **400 BAD_REQUEST** | Body validation failed. The error message includes the field name and reason. |\n\n## Next\n\n[**Lifecycle scenarios →**](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-04-21-using-ramblers-salesforce-mock/lifecycle-scenarios)","contentHtml":"

21-Apr-2026 — Calling the API

\n
\n

Two endpoints are live, both implementing the day-one contract from #209. Both require an Authorization: Bearer <your-token> header, and the tenant in the path must match the tenant the token is scoped to.

\n

← Back to the overview

\n

Try it in Swagger UI

\n

The quickest way to pull data is the interactive API docs, no code required. Go to /docs, click Authorize in the top right, paste your token (without the Bearer prefix), then expand either endpoint and click Try it out. Swagger UI builds the request with the right headers and shows the response inline, so you can list a tenant's members or post a consent change straight from the browser.

\n

\"\"

\n

Swagger UI at /docs: the day-one contract as an interactive console. Authorize once with your token, then expand list members or consent writeback and click Try it out to call it live.

\n

The same contract is published as a machine-readable OpenAPI document at /api/openapi.json, which you can feed to a client generator.

\n

If you would rather script it or wire it into an integration, the curl recipes below hit those same two endpoints.

\n

List members

\n

Returns every non-removed member in the tenant.

\n
TOKEN='rsm_KT50_your-48-hex-token-here'\ncurl -sS \\\n  -H "Authorization: Bearer $TOKEN" \\\n  https://salesforce-mock.ngx-ramblers.org.uk/api/groups/KT50/members \\\n  | jq .\n
\n

The response shape is MemberListResponse (full schema in the OpenAPI document):

\n
{\n  "totalCount": 412,\n  "members": [\n    {\n      "membershipNumber": 3300001,\n      "firstName": "Aoife",\n      "lastName": "Doyle-Adams",\n      "email": "aoife.doyle1@ngx-ramblers.org.uk",\n      "consents": { "emailMarketingConsent": true, ... },\n      "groupMemberships": [ { "groupCode": "KT50", "roles": ["walkLeader"] } ],\n      "membershipExpiryDate": "2026-12-31"\n    }\n  ]\n}\n
\n

The same path /api/groups/{code}/members is used for both group and area tenants today — the route accepts whichever 2-to-6-character code your token is scoped to. The groupCode segment name is a known wrinkle: a parallel /api/areas/{code}/members (or a renamed /api/tenants/{code}/members) is the obvious next step, but tracking ticket ramblers-salesforce-mock#1 currently keeps both kinds on the single path so existing consumers don't have to switch URLs mid-integration.

\n

Incremental sync — ?since=

\n

Pass an ISO-8601 timestamp to get only what's changed since then:

\n
curl -sS \\\n  -H "Authorization: Bearer $TOKEN" \\\n  "https://salesforce-mock.ngx-ramblers.org.uk/api/groups/KT50/members?since=2026-04-01T00:00:00Z" \\\n  | jq .changes\n
\n

The response gains a changes[] array with three kinds of entry: added, updated, and removed. Soft-removed members (those that disappeared in a later upload) appear here with removed, which is how downstream syncs notice deletions without the mock having to keep dead rows in the main members[] array.

\n

If ?since= returns nothing new, check that your timestamp is earlier than the most recent ingest. Freshly ingested rows have updatedAt set to the ingest time; anything before that drops out of changes[].

\n

Include lapsed memberships — ?includeExpired=true

\n

By default the list excludes members whose membership expiry date is in the past. Add ?includeExpired=true to get them too — useful for renewal-reminder workflows.

\n

Writeback a consent change

\n

A single endpoint updates one or more consent flags for a specific member.

\n
curl -sS -X POST \\\n  -H "Authorization: Bearer $TOKEN" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "emailMarketingConsent": false,\n    "source": "ngx-ramblers",\n    "timestamp": "2026-04-21T09:00:00Z",\n    "reason": "unsubscribe-link"\n  }' \\\n  https://salesforce-mock.ngx-ramblers.org.uk/api/members/3300001/consent \\\n  | jq .\n
\n

Returns a ConsentUpdateResponse with the updated flags and success: true. The change is also logged to a consentEvents collection, which is what an HQ-side audit would consult.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldNotes
sourcePer the #209 contract, valid values are ngx-ramblers or mailman. New consumers can be added to the enum if needed — open an issue.
timestampISO-8601. Used to break ties when two systems write competing values.
reasonOptional free-form string for audit context.
Consent flagsAny of emailMarketingConsent, groupMarketingConsent, areaMarketingConsent, otherMarketingConsent — provide only the ones you want to change. At least one must be present. The two xlsx-only flags (postDirectMarketing, telephoneDirectMarketing) are not writeable through this endpoint by design — the source of truth for those remains the Insight Hub upload.
\n

Common errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Status / codeMeaning
401 UNAUTHORIZEDToken missing, malformed, revoked, or unknown. Check the Authorization header; generate a new token if you've lost the original.
401 with "Token is not authorised for tenant X"You're calling /api/groups/X/members with a token generated for a different tenant. Tokens are scoped to one code only — use the right token, or generate one for the right tenant.
404 GROUP_NOT_FOUND / AREA_NOT_FOUNDNo tenant with that code exists. Create it first in the admin UI.
404 MEMBER_NOT_FOUND (consent writeback)No member with that membershipNumber exists in any tenant your token can reach.
400 BAD_REQUESTBody validation failed. The error message includes the field name and reason.
\n

Next

\n

Lifecycle scenarios →

\n"}