> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/secondary-objects.md).

# Secondary Objects

Records synced from connected systems (Mindbody, Mariana Tek, Zenoti, ClubReady, ABC Fitness, and others) — memberships, classes, products, packages, and so on. Each record has a `type` plus type-specific `properties`; `/secondary_object_schemas` describes the fields for each type. Read-only.

## Enumerate the object types configured for this workroom + their fields.

> Returns the secondary object \`type\` values usable in \`GET /secondary\_objects?filter\[type]=...\`.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Secondary Objects","description":"Schema-less-ish objects synced from external systems — memberships, classes, products, packages, etc. Each row has `type` (e.g. \"membership\") plus arbitrary type-specific `properties`. Schemas at `/secondary_object_schemas` describe the expected fields per type. Read-only from v3 in MVP; syncs still land via the legacy `/externalapi/*` integration endpoints (Mariana, Mindbody, Zenoti, Clubready, AbcFitness).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"SecondaryObjectSchema":{"type":"object","properties":{"type":{"type":"string","description":"The object type this schema describes (e.g. \"membership\")."},"object":{"type":"string","enum":["secondary_object_schema"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SecondaryObjectSchemaField"}}}},"SecondaryObjectSchemaField":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"The declared type — commonly `string`, `integer`, `double`, `boolean`, `array`."}}}}},"paths":{"/secondary_object_schemas":{"get":{"tags":["Secondary Objects"],"operationId":"listSecondaryObjectSchemas","summary":"Enumerate the object types configured for this workroom + their fields.","description":"Returns the secondary object `type` values usable in `GET /secondary_objects?filter[type]=...`.","parameters":[{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SecondaryObjectSchema"}}}}]}}}}}}}}}
```

## Retrieve one secondary object type's schema.

> The field definitions for a workroom-defined object type, which is what makes its records interpretable. Read-only.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Secondary Objects","description":"Schema-less-ish objects synced from external systems — memberships, classes, products, packages, etc. Each row has `type` (e.g. \"membership\") plus arbitrary type-specific `properties`. Schemas at `/secondary_object_schemas` describe the expected fields per type. Read-only from v3 in MVP; syncs still land via the legacy `/externalapi/*` integration endpoints (Mariana, Mindbody, Zenoti, Clubready, AbcFitness).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"SecondaryObjectSchema":{"type":"object","properties":{"type":{"type":"string","description":"The object type this schema describes (e.g. \"membership\")."},"object":{"type":"string","enum":["secondary_object_schema"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SecondaryObjectSchemaField"}}}},"SecondaryObjectSchemaField":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"The declared type — commonly `string`, `integer`, `double`, `boolean`, `array`."}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/secondary_object_schemas/{type}":{"get":{"tags":["Secondary Objects"],"operationId":"retrieveSecondaryObjectSchema","summary":"Retrieve one secondary object type's schema.","description":"The field definitions for a workroom-defined object type, which is what makes its records interpretable. Read-only.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecondaryObjectSchema"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List secondary object records of a specific type.

> \`filter\[type]\` is REQUIRED — narrow to one type per request. Optional \`filter\[q]\` matches on the \`name\` field (case-insensitive substring).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Secondary Objects","description":"Schema-less-ish objects synced from external systems — memberships, classes, products, packages, etc. Each row has `type` (e.g. \"membership\") plus arbitrary type-specific `properties`. Schemas at `/secondary_object_schemas` describe the expected fields per type. Read-only from v3 in MVP; syncs still land via the legacy `/externalapi/*` integration endpoints (Mariana, Mindbody, Zenoti, Clubready, AbcFitness).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"SecondaryObject":{"type":"object","description":"A single record of an externally-synced object (a membership, a product, a class, a package, etc.). `type` identifies the schema; `properties` is the type-specific field bag. Consult `/secondary_object_schemas/{type}` for the expected fields.\n","properties":{"id":{"$ref":"#/components/schemas/SecondaryObjectId"},"object":{"type":"string","enum":["secondary_object"]},"type":{"type":"string","description":"The object type. Common values: membership, product, class, package. Check `/secondary_object_schemas` for what this workroom uses."},"properties":{"type":"object","additionalProperties":true,"description":"Type-specific fields — vary per type. See the type's schema."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"SecondaryObjectId":{"type":"string","pattern":"^sobj_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/secondary_objects":{"get":{"tags":["Secondary Objects"],"operationId":"listSecondaryObjects","summary":"List secondary object records of a specific type.","description":"`filter[type]` is REQUIRED — narrow to one type per request. Optional `filter[q]` matches on the `name` field (case-insensitive substring).","parameters":[{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"required":true,"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"REQUIRED. e.g. `membership`, `product`, `class`."},"q":{"type":"string","description":"Optional. Substring match on `name`."}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SecondaryObject"}}}}]}}}}}}}}}
```

## Retrieve one secondary object record.

> A single record of a workroom-defined object type — memberships, products, classes and similar. Read-only. \`listSecondaryObjectSchemas\` returns which types exist.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Secondary Objects","description":"Schema-less-ish objects synced from external systems — memberships, classes, products, packages, etc. Each row has `type` (e.g. \"membership\") plus arbitrary type-specific `properties`. Schemas at `/secondary_object_schemas` describe the expected fields per type. Read-only from v3 in MVP; syncs still land via the legacy `/externalapi/*` integration endpoints (Mariana, Mindbody, Zenoti, Clubready, AbcFitness).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"SecondaryObject":{"type":"object","description":"A single record of an externally-synced object (a membership, a product, a class, a package, etc.). `type` identifies the schema; `properties` is the type-specific field bag. Consult `/secondary_object_schemas/{type}` for the expected fields.\n","properties":{"id":{"$ref":"#/components/schemas/SecondaryObjectId"},"object":{"type":"string","enum":["secondary_object"]},"type":{"type":"string","description":"The object type. Common values: membership, product, class, package. Check `/secondary_object_schemas` for what this workroom uses."},"properties":{"type":"object","additionalProperties":true,"description":"Type-specific fields — vary per type. See the type's schema."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"SecondaryObjectId":{"type":"string","pattern":"^sobj_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/secondary_objects/{id}":{"get":{"tags":["Secondary Objects"],"operationId":"retrieveSecondaryObject","summary":"Retrieve one secondary object record.","description":"A single record of a workroom-defined object type — memberships, products, classes and similar. Read-only. `listSecondaryObjectSchemas` returns which types exist.\n","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecondaryObject"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
