Update lead

PATCH

/leads/{lead_id}

curl --request PATCH \
  --url https://api.nomissedconversions.com/v1/leads/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "note": null }'

Updates a lead’s stage, value, closure status, or note. All changes in a request apply atomically, omitted fields stay unchanged, and no ETag is required.

Set stage to one of the business’s stage keys. Setting value_cents requires currency_code (matching the current business currency) and requires the lead to end the request in the converted stage. A new value_cents replaces the saved amount, and resending the same amount changes nothing. Moving into converted without value_cents starts the value at 0, and moving out of converted clears it.

Set close to an object with a close reason to close the lead, or null to reopen it. You must reopen a closed lead before changing its stage, value, or close reason; reopening and setting a new stage or value can be combined in one request, while changing a close reason requires reopening first. A Converted lead cannot be closed directly, though you can move it to an earlier stage and close it in the same request. The close reason determines whether the lead closes as archived or not_a_lead; some close reasons also move the lead to qualified, and combining one of those reasons with a stage earlier than qualified is rejected.

Set note to update the lead’s note, or send null or a blank string to clear it. If an update would leave behind Google Ads conversions that can no longer be removed, NMC returns 409 (google_ads_conversions_confirmation_required) with those conversions listed; inspect them and resend with confirm_google_ads_conversions_cannot_be_removed set to true to proceed.

Authorizations

• businessAPIKey

Parameters

Path Parameters

lead_id

required

string format: uuid

Request Body^required

Media typeapplication/json

object

>= 1 properties

close

Any of:

object

object

reason

required

string

Allowed values: couldnt_reach_them price_too_high chose_another_company canceled too_busy other too_far_away work_we_dont_do job_too_small wrong_number existing_job job_seeker spam_or_sales_call

null

null

confirm_google_ads_conversions_cannot_be_removed

boolean

currency_code

string

Allowed values: USD CAD

note

string | null

<= 10000 characters

stage

Stable identifier for one of the business’s stages. Built-in keys are new, qualified, and converted; a business may also have custom stages. A stage’s key stays the same even if its display name changes.

string

/^[a-z][a-z0-9_]*$/

value_cents

integer format: int64

<= 2147483647

Examples

{
  "note": null
}

{
  "close": {
    "reason": "price_too_high"
  }
}

{
  "currency_code": "CAD",
  "stage": "converted",
  "value_cents": 125000
}

{
  "close": null,
  "currency_code": "CAD",
  "stage": "converted",
  "value_cents": 125000
}

Responses

200

A lead with the business’s currency and timezone.

Media typeapplication/json

object

business

required

object

currency_code

required

string

Allowed values: USD CAD

id

required

string format: uuid

name

required

string

timezone

required

string

tracking

required

Whether NMC is currently tracking new calls, texts, forms, and forwarded emails for this business. Tracking pauses when the account’s plan isn’t running or its balance drops to $0 or below.

object

since

required

When tracking last switched between active and paused.

string format: date-time

state

required

string

Allowed values: active paused

website_url

required

string

data

required

object

ai_review

required

Any of:

object

object

activity_ids

required

Array<string>

city

required

string | null

contact_first_name

required

string | null

contact_last_name

required

string | null

contact_reason

required

string | null

created_at

required

string format: date-time

id

required

string format: uuid

is_reviewable

required

boolean | null

next_step

required

string | null

status

required

string

Allowed values: pending succeeded failed

street_address

required

string | null

suggested_close_reason

required

Any of:

string

string

Allowed values: couldnt_reach_them price_too_high chose_another_company canceled too_busy other too_far_away work_we_dont_do job_too_small wrong_number existing_job job_seeker spam_or_sales_call

null

null

suggested_stage

required

Any of:

string

Stable identifier for one of the business’s stages. Built-in keys are new, qualified, and converted; a business may also have custom stages. A stage’s key stays the same even if its display name changes.

string

/^[a-z][a-z0-9_]*$/

null

null

summary

required

string | null

updated_at

required

string format: date-time

null

null

close

required

Any of:

object

object

closed_at

required

string format: date-time

closed_by

required

object

api_key_id

required

string | null format: uuid

kind

required

string

Allowed values: account client migration automatic api_key

user_id

required

string | null format: uuid

kind

required

string

Allowed values: archived not_a_lead

reason

required

Any of:

string

string

Allowed values: couldnt_reach_them price_too_high chose_another_company canceled too_busy other too_far_away work_we_dont_do job_too_small wrong_number existing_job job_seeker spam_or_sales_call

null

null

null

null

contact_id

required

string format: uuid

created_at

required

string format: date-time

first_activity_id

required

string format: uuid

id

required

string format: uuid

last_activity_at

required

string format: date-time

note

required

string | null

note_updated_at

required

string | null format: date-time

note_updated_by_api_key_id

required

string | null format: uuid

source

required

object

channel

required

string

Allowed values: website google_ads google_business_profile local_services_ads other

gbraid

required

string | null

gclid

required

string | null

google_ad_group_id

required

string | null

google_ad_id

required

string | null

google_asset_group_id

required

string | null

google_campaign_id

required

string | null

google_device

required

Google Ads {device} ValueTrack value from the ad click (for example, m for mobile).

string | null

google_keyword

required

string | null

google_match_type

required

Google Ads {matchtype} ValueTrack value from the ad click (for example, e for exact match).

string | null

google_network

required

Google Ads {network} ValueTrack value from the ad click (for example, g for Google Search).

string | null

google_target_id

required

string | null

name

required

string

page_url

required

string | null

page_view_id

required

string | null format: uuid

referrer_url

required

string | null

utm_campaign

required

string | null

utm_content

required

string | null

utm_medium

required

string | null

utm_source

required

string | null

utm_term

required

string | null

wbraid

required

string | null

stage

required

Stable identifier for one of the business’s stages. Built-in keys are new, qualified, and converted; a business may also have custom stages. A stage’s key stays the same even if its display name changes.

string

/^[a-z][a-z0-9_]*$/

status

required

string

Allowed values: open archived not_a_lead

updated_at

required

string format: date-time

value_cents

required

Job value in cents in the business currency. Changing the business currency later does not convert saved amounts.

integer format: int64

Example

{
  "business": {
    "currency_code": "USD",
    "tracking": {
      "state": "active"
    }
  },
  "data": {
    "ai_review": {
      "status": "pending",
      "suggested_close_reason": "couldnt_reach_them"
    },
    "close": {
      "closed_by": {
        "kind": "account"
      },
      "kind": "archived",
      "reason": "couldnt_reach_them"
    },
    "source": {
      "channel": "website"
    },
    "status": "open"
  }
}

default

Error response. Status codes: 400 for malformed requests or rejected parameters, 401 for a missing or unrecognized API key, 403 when the account is on hold, the plan isn’t running (which blocks all requests, including reads), or the resource is read-only, 404 when the resource isn’t found, 405 for an unsupported HTTP method, 409 when tracking is paused or the request conflicts with existing input, lead state, business currency, or the webhook endpoint limit, 413 when the body exceeds 64 KiB, 429 when rate limited, 500 for an unexpected server error, and 503 when the service is temporarily unavailable. Retry 500 and 503 errors with backoff (and 429 after Retry-After) by resending the same request, keeping the same submission ID for form submissions. Include X-Request-ID when contacting support.

Media typeapplication/json

The HTTP status code gives the general error category. Show message to the user, and never branch on its text. Include X-Request-ID when contacting support so NMC can match the response to server logs.

object

code

required

Invalid_request: fix the request body or path; when NMC rejected a specific field value, message names that field, while malformed or schema-violating requests return a general contract error. invalid_parameter: remove or fix the query parameter named in param. invalid_page: omit page and restart pagination from the first page with the same filters and limit. invalid_api_key: pass an active business API key in Authorization. account_on_hold: the account is on hold; contact support. plan_inactive: the account’s plan isn’t running; all requests fail until an admin starts the plan in billing. anonymous_contact_read_only: anonymous contacts are read-only and can’t be edited. tracking_paused: tracking is paused for this business, so new form submissions aren’t accepted. not_found: the requested resource doesn’t exist in this business. method_not_allowed: use an HTTP method listed in the Allow header. form_submission_conflict: this submission id was already used with different fields; generate a new UUID for new submissions. contact_identity_conflict: another contact in this business already uses that phone number or email address. phone_has_activities: a contact’s phone number can’t be changed once calls or texts have been recorded for it. recording_processing: the call recording is still processing; retry shortly. currency_changed: the business currency changed; reload /business and resend with the updated currency_code and value_cents. lead_status_conflict: change the lead’s status first as described in message. page_view_conflict: website_page_view_id belongs to a different visitor or page. webhook_endpoint_limit: the business reached its webhook endpoint limit; delete an unused endpoint or contact support. google_ads_conversions_confirmation_required: inspect unremovable_google_ads_conversions and resend with confirm_google_ads_conversions_cannot_be_removed set to true. body_too_large: keep the request body at or below 64 KiB. rate_limited: wait for Retry-After seconds before retrying. internal_error: unexpected server error; retry with exponential backoff. temporarily_unavailable: service temporarily unavailable; retry with exponential backoff.

string

Allowed values: invalid_request invalid_parameter invalid_page invalid_api_key account_on_hold plan_inactive anonymous_contact_read_only tracking_paused not_found method_not_allowed form_submission_conflict contact_identity_conflict phone_has_activities recording_processing currency_changed lead_status_conflict page_view_conflict webhook_endpoint_limit google_ads_conversions_confirmation_required body_too_large rate_limited internal_error temporarily_unavailable

message

required

string

param

string

unremovable_google_ads_conversions

Array<object>

object

conversion_source

required

string

Allowed values: website calls_from_ads

stage_id

required

string format: uuid

stage_name

required

string

Example

{
  "code": "invalid_request",
  "unremovable_google_ads_conversions": [
    {
      "conversion_source": "website"
    }
  ]
}

Headers

Allow

string

Retry-After

integer

WWW-Authenticate

string