Create a document for a member

POST /api/members/{memberId}/documents

Success: 200 OK

Products: Operator (FOH), Consumer (CONSUMER) (any one of these products, not all)
Features: Online Bookings (ONLINEBOOK), Online Joining (ONLINEJOIN), Front of House Generic Access (FOHGENERIC) (any one of these features, not all)

Overview

Uploads a file you already hold — a signed form, a photo of an ID card, a scanned letter — and files it against a member's record. The request is multipart/form-data and must carry exactly two parts: file, the bytes of the document, and json, a JSON object describing it. On success you get 200 OK and the body is a single JSON string containing a read-only link to the stored file.

Reach for this endpoint when the finished file already exists on your side. If instead you want Gladstone to build the file for you by stamping values into a stored PDF template, use Create a templated document for a member, which takes no file at all.

The json part must be a JSON object with these fields — anything that fails to parse as JSON is rejected with 400 carrying the parser's own message:

name (string, required, max 255 characters) — the document's title. It is what Retrieves all documents associated with a member returns as the document name; the uploaded file's own filename is kept separately.
documentTypeId (integer, required) — the category the document is filed under, taken from Returns all document types. It must already exist, and must not be negative.
fileType (required) — PDF, JPG, JPEG or PNG, sent as the name (matched case-insensitively) or as its numeric value. Anything unrecognised is treated as absent and rejected with The type of the file must be provided and be valid.
isSensitive (boolean) — marks the document as sensitive. Defaults to false when omitted, but it is a floor rather than a switch: if the document type itself is configured as sensitive, the stored document is forced to sensitive regardless of what you send.
expiryDate (date-time, optional) — the date the document stops being valid, returned as the document's valid-to date. A date earlier than today is rejected with Date must not be in the past. Omit it for a document that never expires.

Two things routinely surprise integrators. First, the declared fileType is checked against the file's actual binary signature, not its extension, so a .pdf that is really a JPEG fails. Second, documents created here are not visible to the member: this request has no field to change that, and when a member's own token lists their documents, only member-visible ones are returned, so the member will not see what you uploaded.

The URL you get back is a short-lived signed link — valid for 20 minutes, plus 20 minutes' allowance for clock skew — so treat it as single-use and do not store it. To get a fresh link later, call Retrieve a document associated with a member.

Access is checked first: when your token carries a member id it must equal {memberId} or the request is rejected with 403 and The given member ID of {memberId} does not belong to the logged in member. This route does not accept linked members, so a parent's token cannot upload against a child's record here. Tokens with no member id in them (staff and integration tokens) are not subject to that check.

Be aware that a Cloudflare managed challenge sits in front of this route in some environments and can return 403 to non-browser clients posting multipart form data before the request ever reaches the API. If you see an unexplained 403 with an HTML body, that is the likely cause.

Endpoint

POST {base_url}/api/members/{memberId}/documents

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`memberId`	integer (int32)	Yes	The member the document is filed against. The member must exist, or the call fails with `404` and `The member with the ID {memberId} doesn't exist`. It is also the id you pass to Retrieves all documents associated with a member to read the document back. When your token carries a member id, this value must equal it — linked members are not accepted on this route.

Sample request

cURL

curl -X POST '{base_url}/api/members/{memberId}/documents' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Sample response

200 OK

"string"

Errors

Status	Meaning	When
`400`	Bad request	The form data did not carry exactly one file — `A document must be provided when uploading`; the `json` part was missing or empty — `A json request must be provided when uploading`; the `json` part did not parse, in which case the parser's message is returned verbatim; the first failing field validation, such as `The type of the file must be provided and be valid`, `Document type ID must be a non-negative number` or `Date must not be in the past`; the file exceeded 10MB — `The file size is larger than 10MB and can not be uploaded. Current file size: {size}MB`; or the file's real format did not match the declared `fileType` — `The file was not valid for the given type of {fileType} - the actual type was {actualType} (blank if type was unrecognizable)`.
`404`	Not found	No member has the id in the path — `The member with the ID {memberId} doesn't exist` — or the `documentTypeId` in the JSON part matches no configured document type — `The document type with the ID {documentTypeId} doesn't exist`.
`500`	Internal server error	Storing the file failed, or another unexpected server-side failure occurred. The document record is created before the file is stored, so a failure at that point can leave a document record with no file behind it — check with Retrieves all documents associated with a member before retrying.

This page as markdown · All pages · llms.txt