> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update CRM Overview
> Create or update a subscriber's CRM deal via the ChatSyncs API: title, pipeline, stage, value, currency, expected close date, owner, lead score and source. Use when a developer asks how to create a deal or move a contact to another stage programmatically.
Creates a subscriber's CRM deal, or updates it. Read the current deal, and the `pipeline_id` and `stage_id` it uses, with
[CRM Overview](/developer-api/subscriber/get-crm-overview).
## Example Request
```bash theme={null}
curl -X POST 'https://platform.chatsyncs.com/api/v1/whatsapp/subscriber/crm/update' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'title=New Deal' \
-d 'stage_id=2252' \
-d 'value=500.00' \
-d 'currency=USD' \
-d 'expected_close_date=2026-10-15' \
-d 'owner_user_id=12' \
-d 'lead_score=hot' \
-d 'source=WhatsApp'
```
Only `phone_number_id` and `phone_number` are required. A successful call answers
`{"status":"1","message":"CRM Overview updated successfully"}`.
## How it behaves
**The first call creates the deal**, in the default pipeline at its first stage, titled with the subscriber's name and with
the source `WhatsApp`. That happens even if you send no optional fields.
**Fields you leave out are kept.** Unlike [Subscriber Update](/developer-api/subscriber/update-subscriber), changing only the
lead score leaves the title, value, stage and the rest exactly as they were.
| Field | Rule |
| - | - |
| `title` | Up to 255 characters. An empty value resets it to the subscriber's name. |
| `value` | A number, zero or more. A negative or non-numeric value is rejected. |
| `expected_close_date` | `YYYY-MM-DD`. Any other format is rejected. |
| `lead_score` | `hot`, `warm` or `cold`, **in lower case** — `Hot` is rejected. |
| `owner_user_id` | A team member id from [Team Member List](/developer-api/user/list-team-members). An unknown id is rejected (`Invalid deal owner`); an inactive member is accepted. |
| `currency` | Not validated: any text is accepted, and it is stored in upper case (`eur` becomes `EUR`). Use a three-letter code. |
| `pipeline_id`, `stage_id` | Whole numbers. **See the warning below.** |
**A stage or pipeline that doesn't exist is silently ignored.** The call still answers `CRM Overview updated successfully`
and the deal stays where it was — so a success response does **not** prove the deal moved. Read it back with
[CRM Overview](/developer-api/subscriber/get-crm-overview) and compare `stage_id`. In the account tested, one pipeline had
the stages *New*, *Qualified*, *Proposal* and *Negotiation*; ids belonging to other pipelines, or to nothing, did not move the
deal.
An unknown subscriber is answered with `{"status":"0","message":"Subscriber not found"}`, and a missing
`phone_number_id` or `phone_number` with `The phone number id field is required., The phone number field is required.`
## OpenAPI
````yaml POST /whatsapp/subscriber/crm/update
openapi: 3.1.0
info:
title: ChatSyncs Developer API
version: 1.0.0
description: >-
REST API for sending WhatsApp messages and managing subscribers through
ChatSyncs.
**Authentication.** Send your key as the `apiToken` parameter, or as
`Authorization: Bearer ` — both work on every endpoint. A wrong key
returns HTTP 401 `{"status":"0","message":"Unauthenticated."}`; no key at
all redirects to the login page.
**Methods.** Every endpoint accepts both GET and POST with the same
parameters, except Upload Media, which is POST-only. Use POST for anything
that changes data.
**Errors.** Failures usually come back as HTTP 200 with `"status":"0"` and
the reason in `message`, so always check `status`. `status` is the string
`"1"` or `"0"` on most endpoints and a boolean on a few.
**Lists.** Endpoints that return rows put them in `message` as a list; there
is no `data` field (Custom Fields List is the exception and uses `data`).
servers:
- url: https://platform.chatsyncs.com/api/v1
security: []
paths:
/whatsapp/subscriber/crm/update:
post:
tags:
- Subscriber API
summary: Update CRM Overview
description: >-
Creates or updates the subscriber's CRM deal. The first call creates the
deal in the default pipeline, at its first stage, titled with the
subscriber's name and with the source `WhatsApp`; even a call with no
optional fields does this. **Later calls change only the fields you
send** — everything else is kept (unlike Subscriber Update).
`lead_score` is `hot`, `warm` or `cold`, lower case.
`expected_close_date` is `YYYY-MM-DD`. `owner_user_id` must be a team
member (an unknown id is rejected; an inactive member is accepted). An
empty `title` resets it to the subscriber's name. **Not checked:** a
`stage_id` or `pipeline_id` that does not exist is silently ignored
while the call reports success, and `currency` accepts any text (`eur`
is stored as `EUR`). Read the deal back with CRM Overview to confirm a
stage move.
operationId: updateCrmOverview
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
apiToken:
type: string
description: >-
Your ChatSyncs API key (not a WhatsApp/Meta access token).
[Where to find
it](/developer-api/finding-ids#api-token-apitoken).
example: API-KEY
phone_number_id:
type: string
description: >-
The WhatsApp account's phone number ID. [Where to find
it](/developer-api/finding-ids#phone-number-id-phone_number_id).
example: PHONE-NUMBER-ID
phone_number:
type: string
description: >-
The subscriber's phone number, with country code, digits
only.
example: PHONE-NUMBER
title:
type: string
description: Deal title, up to 255 characters.
example: New Deal
pipeline_id:
type: integer
description: >-
Pipeline id, from CRM Overview. Ignored if it is not a
pipeline of this account.
example: 376
stage_id:
type: integer
description: >-
Stage id within the subscriber's pipeline, from CRM
Overview. Ignored, with a success response, if it is not a
stage of that pipeline.
example: 2252
value:
type: number
description: Deal value. Zero or more.
example: 500
currency:
type: string
description: >-
Currency code such as USD, BDT, MYR or EUR. Stored
upper-case; not validated.
example: USD
expected_close_date:
type: string
description: Expected close date, `YYYY-MM-DD`.
example: '2026-10-15'
owner_user_id:
type: integer
description: 'The deal owner: a team member id from Team Member List.'
example: 12
lead_score:
type: string
enum:
- hot
- warm
- cold
description: Lead score, lower case.
example: hot
source:
type: string
description: Where the lead came from.
example: WhatsApp
required:
- apiToken
- phone_number_id
- phone_number
responses:
'200':
description: >-
Standard ChatSyncs response. `status` is `"1"` on success and `"0"`
on failure.
content:
application/json:
schema:
type: object
properties:
status:
type: string
message: {}
examples:
success:
summary: Success
value:
status: '1'
message: CRM Overview updated successfully
badScore:
summary: lead_score is not hot, warm or cold
value:
status: '0'
message: The selected lead score is invalid.
badDate:
summary: Date is not YYYY-MM-DD
value:
status: '0'
message: The expected close date does not match the format Y-m-d.
badValue:
summary: value is negative or not a number
value:
status: '0'
message: The value must be at least 0.
badOwner:
summary: owner_user_id is not a team member
value:
status: '0'
message: Invalid deal owner
longTitle:
summary: Title is too long
value:
status: '0'
message: The title must not be greater than 255 characters.
notFound:
summary: Unknown subscriber
value:
status: '0'
message: Subscriber not found
error:
summary: A required field is missing
value:
status: '0'
message: >-
The phone number id field is required., The phone number
field is required.
'401':
description: >-
`apiToken` is wrong. (With no token at all the API redirects to the
login page with HTTP 302 instead of returning JSON.)
content:
application/json:
schema:
type: object
properties:
status:
type: string
message:
type: string
examples:
unauthenticated:
summary: Wrong apiToken
value:
status: '0'
message: Unauthenticated.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.