# Create a prospect interaction

`POST /api/members/prospects/{memberId}/interactions`

- **Success:** `201 Created`
- **Products:** not restricted by product
- **Features:** Prospecting (`PROSPECTS`)

HTML version: [Create a prospect interaction](https://support.gladstonesoftware.cloud/reference/members/create-a-prospect-interaction)

## 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](get-the-prospect-interaction-sub-types-for-an-interaction-type.md); 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](get-the-prospect-interaction-outcomes-for-an-interaction-type.md) 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](update-a-prospect-interaction.md) and [Delete a prospect interaction](delete-a-prospect-interaction.md). 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](../../guides/authenticating-with-gladstone-apis.md).

## 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](get-the-prospect-interaction-sub-types-for-an-interaction-type.md). 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](get-the-prospect-interaction-outcomes-for-an-interaction-type.md) 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](get-a-members-prospect-interactions.md), 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

```bash title="cURL"
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](update-a-prospect-interaction.md) and [Delete a prospect interaction](delete-a-prospect-interaction.md). |
| `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

```json title="201 Created"
{
  "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. |