PATCH /v1/agency/prospects/{prospect_id}

Update a prospect

scope write:prospects cost 2 RU idempotent optional

Edit a prospect's details or move it: won turns its brand into a client brand and can invite the client to a client seat, create three kickoff tasks and schedule a weekly report with the same prompts and engines (each step on its own: the answer says which ran), and a second won changes nothing; lost keeps a reason and a day to look again; new reopens a lost deal, back to ready when its report is done (generating while it runs). Free. Needs Agency Plus; a key restricted to one brand answers 403 forbidden.

Path parameters

prospect_id string required

Prospect id (UUID).

Query parameters

dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Header parameters

Idempotency-Key string optional

Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required

Type: ProspectUpdateRequest

company_name string (nullable) nullable
contact_email string (nullable) nullable
contact_name string (nullable) nullable
contact_title string (nullable) nullable
create_tasks boolean

Won: three kickoff tasks on the client's brand.

default: `false`
description string (nullable) nullable
invite_email string (nullable) nullable

Won: invite this person to a client seat.
linkedin_url string (nullable) nullable
lost_note string (nullable) nullable
lost_reason enum (nullable) nullable
phone string (nullable) nullable
revisit_at string (nullable) nullable

Day a lost deal is due another look.
schedule_report boolean

Won: a weekly report with the prospect report's prompts and engines.

default: `false`
stage enum (nullable) nullable
website string (nullable) nullable

Example payload

{
  "lost_reason": "timing",
  "revisit_at": "2027-04-16",
  "stage": "lost"
}

Responses

Updated a prospect application/json

Type: ProspectUpdated

prospect_id string required
status enum required
object string

default: `prospect.update`
scheduled_report_id string (nullable) nullable
seat_error string (nullable) nullable

Why the client seat could not be invited.
seat_invited boolean

default: `false`
tasks_created integer

default: `0`

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request body did not match the expected schema application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request PATCH \
  --url 'https://api.rankprompt.com/v1/agency/prospects/your_prospect_id_here?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "lost_reason": "timing",
  "revisit_at": "2027-04-16",
  "stage": "lost"
}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/agency/prospects/your_prospect_id_here?dry_run=false';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"lost_reason":"timing","revisit_at":"2027-04-16","stage":"lost"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/agency/prospects/your_prospect_id_here"

querystring = {"dry_run":"false"}

payload = {
    "lost_reason": "timing",
    "revisit_at": "2027-04-16",
    "stage": "lost"
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers, params=querystring)

print(response.json())