Create a prospect interaction
POST /api/members/prospects/{memberId}/interactions
Success: 201 Created
- Products: not restricted by product
- Features: Prospecting (
PROSPECTS)
Overview
Records one interaction — a call, a task or an appointment — against a prospect. A prospect is not a separate kind of record: it is an ordinary member whose member status carries the prospect indicator (the status configuration documents it as 0:Not a prospect; 1:Member is Prospect), which is why this route sits under /api/members/ and is addressed by member id. Only the member's existence is checked, not whether they currently hold a prospect status, so the call succeeds for any member id.
Two lookups drive the shape of the record and you should read them before you post. interactionSubTypeId is required and comes from Get the prospect interaction sub types for an interaction type; it decides whether the interaction is a call, a task or an appointment, and that classification is returned to you rather than set by you. outcomeOfInteractionTypeId, if you record an outcome at the same time, comes from Get the prospect interaction outcomes for an interaction type called with that same interaction type. Both references are re-checked server-side, and an outcome that belongs to a different interaction type from the sub type is rejected even though both ids exist.
The audit fields are owned by the server: raisedByUserId, raisedDate, lastActionUserId and lastActionDate are stamped from the logged-in user on your request and the current time, and there is no way to backdate an interaction through this endpoint. The response is the stored record including the generated id, which is the id you pass to Update a prospect interaction and Delete a prospect interaction. Unlike most member routes in this API, this endpoint does not compare the memberId in the path against the member in your token, so any caller authorised for it can record an interaction against any member.
Endpoint
POST {base_url}/api/members/prospects/{memberId}/interactions
{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 interaction is recorded against. Must be a positive integer — zero or a negative value is rejected with 400 before anything is read — and must belong to an existing member, or the request fails with 422. Any member id is accepted; the member does not need to hold a prospect status. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
interactionSubTypeId | string | Yes | The sub type that classifies the interaction, taken from Get the prospect interaction sub types for an interaction type. It fixes the interaction type returned in interactionTypeId and interactionType, and it constrains which outcomeOfInteractionTypeId you may send. Missing or empty gives 400, longer than 15 characters gives 400, and an id that is not in the lookup gives 422. |
details | string | No | Free-text notes about the interaction, up to 4000 characters; longer values are rejected with 400 details must be 4000 characters or fewer. Omit it and the interaction is stored with no notes. |
nextActionDate | string (date-time) | No | When the next action on this interaction falls due. No range check is applied, so a date in the past is accepted. This field is converted between the value you send and the operator's local time zone, so send an explicit offset (as in the sample) rather than a bare local time. Omit it and no next action date is stored. |
scheduledWith | string | No | Stored and returned unchanged, up to 15 characters; longer values are rejected with 400 scheduledWith must be 15 characters or fewer. The value is not checked against any user, staff or member record. |
scheduledBy | string | No | Stored and returned unchanged, up to 15 characters; longer values are rejected with 400 scheduledBy must be 15 characters or fewer. The value is not checked against any user, staff or member record. |
outcomeOfInteractionTypeId | integer (int32) | No | The outcome recorded against the interaction, taken from Get the prospect interaction outcomes for an interaction type called with the interaction type your sub type belongs to. Outcomes are scoped to an interaction type, so an outcome that exists but belongs to a different type from interactionSubTypeId is rejected with 422. Omit it to create the interaction with no outcome and set one later with the update endpoint. |
duration | integer (int32) | No | How long the interaction lasts, in minutes. Must be between 5 and 30 inclusive; anything else is rejected with 400 duration must be between 5 and 30 minutes. Omit it and no duration is stored. |
priority | integer (enum) | No | How urgent the interaction is: 1 low, 2 medium, 3 high. Omit it and the interaction is stored with no priority. |
emailConfirmationType | integer (int32) | No | Stored and echoed back unchanged; this endpoint applies no validation to it and takes no action on it. |
interactionStatus | integer (enum) | No | Where the interaction has got to: 1 active, 2 completed, 3 overdue, 4 unassigned. The same values are the status filter on Get a member's prospect interactions, so an interaction created without a status will not come back from a status-filtered read. |
reminder | integer (int32) | No | How many minutes before the interaction a reminder is due, from 0 to 30, or -1 for no reminder. Any other value is rejected with 400 reminder must be -1 (none) or between 0 and 30 minutes. Omit it and no reminder value is stored. |
Sample request
curl -X POST '{base_url}/api/members/prospects/{memberId}/interactions' \
-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
}'Response fields
| Field | Type | Description |
|---|---|---|
id | integer (int32) | The identifier of the interaction that was created. Keep it: it is the {id} segment for Update a prospect interaction and Delete a prospect interaction. |
memberId | integer (int32) | The member the interaction was recorded against. Always echoes the memberId from the path — there is no way to record an interaction against a different member. |
interactionSubTypeId | string | The sub type you sent, unchanged. |
interactionTypeId | string | The interaction type the sub type belongs to, determined by the sub type. You never set this directly; it follows from interactionSubTypeId. |
interactionType | integer (enum) | The same interaction type resolved to a known value: 0 call, 1 task, 2 appointment. Null when interactionTypeId is not one of those three values, so read interactionTypeId if you need the raw value in every case. |
details | string | The notes stored against the interaction. Null when you did not send any. |
nextActionDate | string (date-time) | The stored next action date. Null when you did not send one. |
scheduledWith | string | The value you sent, unchanged. Null when you did not send one. |
scheduledBy | string | The value you sent, unchanged. Null when you did not send one. |
outcomeOfInteractionTypeId | integer (int32) | The outcome stored against the interaction. Null when you did not record one. |
duration | integer (int32) | The stored duration in minutes. Null when you did not send one. |
priority | integer (enum) | 1 low, 2 medium, 3 high. Null when you did not send one. |
emailConfirmationType | integer (int32) | The value you sent, unchanged. Null when you did not send one. |
interactionStatus | integer (enum) | 1 active, 2 completed, 3 overdue, 4 unassigned. Null when you did not send one. |
reminder | integer (int32) | The stored reminder in minutes, or -1 for no reminder. Null when you did not send one. |
raisedByUserId | string | The user who raised the interaction, taken from the logged-in user on your request. Set by the server; anything you send for it in the body is ignored. |
raisedDate | string (date-time) | The moment the interaction was created, taken from the server clock in UTC. There is no way to backdate it. |
lastActionUserId | string | The user who last touched the interaction. Equal to raisedByUserId on create, and re-stamped from the logged-in user on every update. |
lastActionDate | string (date-time) | When the interaction was last touched. Equal to raisedDate on create, and re-stamped on every update, so use it to detect changes made after you wrote the record. |
Sample response
{
"id": 12345,
"memberId": 12345,
"interactionSubTypeId": "string",
"interactionTypeId": "string",
"interactionType": 0,
"details": "string",
"nextActionDate": "2026-08-14T19:00:00Z",
"scheduledWith": "string",
"scheduledBy": "string",
"outcomeOfInteractionTypeId": 12345,
"duration": 1,
"priority": 1,
"emailConfirmationType": 1,
"interactionStatus": 1,
"reminder": 1,
"raisedByUserId": "string",
"raisedDate": "2026-08-14T19:00:00Z",
"lastActionUserId": "string",
"lastActionDate": "2026-08-14T19:00:00Z"
}Errors
| Status | Meaning | When |
|---|---|---|
400 | Bad request | memberId is zero or negative, the body is missing, or interactionSubTypeId is empty: A valid memberId and a non-empty interactionSubTypeId are required. Also returned, before any reference is looked up, for duration must be between 5 and 30 minutes., reminder must be -1 (none) or between 0 and 30 minutes., details must be 4000 characters or fewer., scheduledWith must be 15 characters or fewer., scheduledBy must be 15 characters or fewer. and interactionSubTypeId must be 15 characters or fewer. |
422 | Unprocessable entity | A reference in the request cannot be resolved, or two references do not fit together. The body is the first problem found: Member {memberId} does not exist., Interaction sub type '{id}' does not exist., Interaction outcome {id} does not exist., or Interaction outcome {id} is not valid for interaction sub type '{id}'. when the outcome belongs to a different interaction type from the sub type. |
500 | Internal server error | An unexpected server-side failure while saving the interaction. The body is empty. Nothing is returned about the interaction, so re-read the member's interactions before retrying. |