Update a prospect interaction
PUT /api/members/prospects/{memberId}/interactions/{id}
- Products: not restricted by product
- Features: Prospecting (
PROSPECTS)
Overview
Updates an existing prospect interaction — a logged contact with a prospective member, such as a call, a tour or a follow-up, recorded against their record while sales staff work the lead.
This is a partial update. Every field falls back to its current value, so anything you omit or send as null keeps its current value. There is no way to blank a text field or clear a date through this endpoint. The last-action user and last-action date are stamped by the server on every successful call, and any value you supply for them is ignored.
The interaction must belong to the member in the path: the record is looked up by both ids together, so a valid interaction id under the wrong member returns 404.
Two references are cross-checked before anything is written, and the check runs against the merged record, not just what you sent. If you change only the outcome, it is validated against the sub type already stored; if you change only the sub type, it is validated against the stored outcome. An outcome that does not belong to the same interaction type as the sub type is rejected with 422 even though both values exist. Get valid values from Get the prospect interaction sub types for an interaction type and Get the prospect interaction outcomes for an interaction type.
Endpoint
PUT {base_url}/api/members/prospects/{memberId}/interactions/{id}
{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 prospect the interaction belongs to. Must be greater than 0, and must exist — a member that does not exist returns 422, not 404. |
id | integer (int32) | Yes | The id of the interaction to update, from Get a member's prospect interactions. It must belong to {memberId} or the call returns 404. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
interactionSubTypeId | string | No | The specific kind of contact within an interaction type — for example a particular sort of call or appointment. Maximum 15 characters, and must exist. Omit or send null to leave it unchanged; an empty or whitespace string is explicitly rejected with 400 rather than being written. Changing it re-checks the stored outcomeOfInteractionTypeId for compatibility. |
details | string | No | Free-text notes about what happened. Maximum 4000 characters. Omit or send null to keep the existing notes — they cannot be cleared here. |
nextActionDate | string (date-time) | No | When the next follow-up is due. Stored in the tenant's local time zone. Omit or send null to keep the current date; there is no way to remove a scheduled follow-up through this endpoint. |
scheduledWith | string | No | The staff member the interaction is scheduled with. Maximum 15 characters. Not validated against the user list. Omit or send null to leave unchanged. |
scheduledBy | string | No | The staff member who arranged the interaction. Maximum 15 characters. Not validated against the user list. Omit or send null to leave unchanged. |
outcomeOfInteractionTypeId | integer (int32) | No | The result of the interaction, from the outcomes configured for its interaction type. Must exist, and must belong to the same interaction type as the sub type on the merged record, or the call fails with 422. Omit or send null to leave the outcome unchanged. |
duration | integer (int32) | No | How long the interaction took, in minutes. Must be between 5 and 30 inclusive; anything else returns 400. Omit or send null to leave it unchanged. |
priority | integer (enum) | No | How urgent the interaction is: 1 low, 2 medium, 3 high. Send the number, not the name. Omit or send null to leave the priority unchanged. |
emailConfirmationType | integer (int32) | No | Which confirmation email is associated with the interaction. Omit or send null to leave it unchanged. |
interactionStatus | integer (enum) | No | Where the interaction has got to: 1 active, 2 completed, 3 overdue, 4 unassigned. Send the number, not the name. Not cross-checked against nextActionDate or the outcome, so marking an interaction completed is entirely up to you. Omit or send null to leave the status unchanged. |
reminder | integer (int32) | No | How many minutes before the interaction a reminder should fire. Must be -1 for no reminder, or between 0 and 30 inclusive; anything else returns 400. Omit or send null to leave the reminder unchanged — send -1 to turn it off. |
Sample request
curl -X PUT '{base_url}/api/members/prospects/{memberId}/interactions/{id}' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true' \
-H 'Content-Type: application/json' \
-d '{
"interactionSubTypeId": "string",
"details": "string",
"nextActionDate": "2026-08-14T19:00:00Z",
"scheduledWith": "string",
"scheduledBy": "string",
"outcomeOfInteractionTypeId": 12345,
"duration": 1,
"priority": 1,
"emailConfirmationType": 1,
"interactionStatus": 1,
"reminder": 1
}'Errors
A successful call returns 204 No Content. Note the split: value-shape problems are 400, while references that do not resolve are 422.
| Status | Meaning | When |
|---|---|---|
400 | Bad request | memberId is 0 or negative, or the body is missing: A valid memberId and request body are required. |
400 | Bad request | interactionSubTypeId was supplied as an empty or whitespace string: interactionSubTypeId, when supplied, must be a non-empty value. |
400 | Bad request | duration is outside 5–30: duration must be between 5 and 30 minutes. |
400 | Bad request | reminder is not -1 and is outside 0–30: reminder must be -1 (none) or between 0 and 30 minutes. |
400 | Bad request | A field is too long: details must be 4000 characters or fewer., scheduledWith must be 15 characters or fewer., scheduledBy must be 15 characters or fewer., interactionSubTypeId must be 15 characters or fewer. |
404 | Not found | No interaction with that id belongs to that member: Interaction {id} was not found for member {memberId}. |
422 | Unprocessable entity | The prospect does not exist: Member {memberId} does not exist. |
422 | Unprocessable entity | interactionSubTypeId is not configured: Interaction sub type '{interactionSubTypeId}' does not exist. |
422 | Unprocessable entity | outcomeOfInteractionTypeId is not configured: Interaction outcome {id} does not exist. |
422 | Unprocessable entity | The outcome belongs to a different interaction type from the sub type on the merged record: Interaction outcome {id} is not valid for interaction sub type '{subTypeId}'. |
500 | Internal server error | Saving the change failed, or another unexpected server-side failure occurred. No detail is returned in the body. |