Update Business Profile

What it does

Updates the WhatsApp business profile (PATCH = partial update; only the fields you send are changed). The change is written directly to Meta — no caching. With Prefer: return=representation the updated profile is returned; with return=minimal no body is returned.

Profile update is partial: send only the fields you want to change; the rest are preserved.

Endpoint

PATCH /api/v1/wa/{app_id}/profile

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

string

required

Always application/json.

string

return=representation (default) returns the updated profile; return=minimal returns no body. The applied preference is reported via the Preference-Applied: return=... header.

No body needed? On updates, use Prefer: return=minimal for a faster call that skips the read-back and returns just { "isSuccess": true } with HTTP 200.

Path parameters

string

required

Application ID. Must belong to the organization (otherwise 404).

Request Body

All fields are optional; only the fields you send are updated. Fields you do not send remain as they are on Meta.

string

“About” text (max 139 chars).

string

Business address (max 256 chars).

string

Business description (max 512 chars).

string

Contact email (valid email).

string

Media handle for the new profile picture — not a URL and not raw file bytes. Upload the image first with Upload Media and send the handle you get back — the Changing the profile picture section below walks through both steps.

A handle is single-use. Meta consumes it the moment the profile update succeeds; the same value cannot be sent again. To change the picture a second time, upload the file again and use the new handle.

string

Business category (mapped to Meta’s vertical) — e.g. RETAIL, HEALTH, FINANCE, RESTAURANT, OTHER. A value outside the list returns 422. See Business Profile Category for all 23 values.

string[]

Business websites (max 2, http(s)://).

Changing the profile picture

The profile picture is the one field that is not sent inline. It is a two-step flow: upload the image to get a handle, then reference that handle in the profile update.

Upload the image

POST /api/v1/wa/{app_id}/media/upload
Authorization: Bearer sk_...
Content-Type: multipart/form-data; boundary=----boundary

{ "data": { "handle": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value" }, "isSuccess": true }

Use image/jpeg or image/png, up to 5 MB. See Upload Media.

Send the handle as profilePictureReference

PATCH /api/v1/wa/{app_id}/profile
Authorization: Bearer sk_...
Content-Type: application/json

{ "profilePictureReference": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value" }

The handle is forwarded to Meta as the profile picture; the stored image is then served back as profilePictureUrl on subsequent reads.

The handle is consumed by this call. It is a one-time reference, not a reusable asset ID — replaying the same profilePictureReference on a later update fails. Upload the file again whenever you want to set the picture again, and do not cache handles between requests.

profilePictureReference is write-only: it never appears in a response. Reads return the resulting image as profilePictureUrl instead. Because the update is partial, sending profilePictureReference on its own leaves every other profile field untouched.

Response

With Prefer: return=representation (default), the response is { "data": {...}, "isSuccess": true } — the full profile re-fetched from Meta after the update. With return=minimal, the response is { "isSuccess": true }.

boolean

true when the update was accepted.

object | null

The updated profile (same shape as Get Business Profile: about, address, description, email, profilePictureUrl, websites, category — all optional; unset fields are dropped). A picture set through profilePictureReference comes back as profilePictureUrl; the handle itself is never echoed. With Prefer: return=minimal the key is omitted from the envelope altogether — the response is exactly { "isSuccess": true }, still with HTTP 200.

Examples

Demo 1 — update a single field (representation)

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Prefer: return=representation
Content-Type: application/json

{ "about": "Open 09:00-18:00" }

Response (Preference-Applied: return=representation) — full updated profile:

{
  "data": {
    "about": "Open 09:00-18:00",
    "address": "Levent, Istanbul",
    "email": "hello@acme.com",
    "websites": ["https://acme.com"],
    "category": "RETAIL"
  },
  "isSuccess": true
}

Demo 2 — update multiple fields

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Prefer: return=representation
Content-Type: application/json

{
  "about": "Premium support 7/24",
  "email": "support@acme.com",
  "websites": ["https://acme.com", "https://shop.acme.com"],
  "category": "RETAIL"
}

{
  "data": {
    "about": "Premium support 7/24",
    "email": "support@acme.com",
    "websites": ["https://acme.com", "https://shop.acme.com"],
    "category": "RETAIL"
  },
  "isSuccess": true
}

Demo 3 — minimal (no body wanted)

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Prefer: return=minimal
Content-Type: application/json

{ "description": "We sell quality goods." }

Response (Preference-Applied: return=minimal) — still HTTP 200, and data is omitted entirely rather than sent as null:

{ "isSuccess": true }

Demo 4 — update category (vertical)

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Content-Type: application/json

{ "category": "HEALTH" }

{
  "data": { "about": "Open 09:00-18:00", "email": "hello@acme.com", "category": "HEALTH" },
  "isSuccess": true
}

Demo 5 — set the profile picture (upload → handle → update)

First upload the image and keep the handle:

POST /api/v1/wa/app_7poyXj8GXuv76e/media/upload
Authorization: Bearer sk_...
Content-Type: multipart/form-data; boundary=----boundary

{ "data": { "handle": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value" }, "isSuccess": true }

Then reference it in the profile update (optionally alongside other fields):

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Prefer: return=representation
Content-Type: application/json

{
  "profilePictureReference": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value",
  "about": "Open 09:00-18:00"
}

{
  "data": {
    "about": "Open 09:00-18:00",
    "email": "hello@acme.com",
    "profilePictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/sample_profile_picture",
    "websites": ["https://acme.com"],
    "category": "RETAIL"
  },
  "isSuccess": true
}

The handle is now spent. Changing the picture again means uploading the file again for a fresh handle.

Demo 6 — error: reusing a spent handle → 400

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Content-Type: application/json

{ "profilePictureReference": "4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value" }

Meta rejects a handle that has already been consumed (or was never valid):

{ "errors": { "code": "META_033", "group": "VALIDATION", "description": "Failed to update business profile. Details: ..." }, "isSuccess": false }

Demo 7 — error: more than 2 websites → 422

PATCH /api/v1/wa/app_7poyXj8GXuv76e/profile
Authorization: Bearer sk_...
Content-Type: application/json

{ "websites": ["https://a.com", "https://b.com", "https://c.com"] }

Because websites exceeds 2, a 422 (validation) is returned without reaching Meta.

Errors

object

Error details with code, group, and description; isSuccess is false.

HTTP	Code	Group	When
401	`ORGANIZATION_SECRET_010`	`NOT_FOUND`	Authorization / secret key is missing.
401	`ORGANIZATION_SECRET_011`	`NOT_FOUND`	Secret key is invalid.
404	`APPLICATION_004`	`NOT_FOUND`	`app_id` does not belong to the organization.
422	`WA_VAL_001`	`VALIDATION`	More than 2 `websites`.
422	`VAL_*` (FastAPI validation)	`VALIDATION`	`about` > 139, `address` > 256, `description` > 512, invalid email/URL, invalid `category` enum value.
401	`META_030`	`AUTHENTICATION`	Meta access token invalid/expired (190).
403	`META_031`	`NOT_ALLOWED`	Meta permission denied (10 / 200–299).
429	`META_032`	…	Meta rate limit (4 / 80007).
400	`META_033`	`VALIDATION`	Meta invalid parameter (100) — including a `profilePictureReference` handle that is expired, already consumed, or was not produced by Upload Media.
502	`META_002`	`SERVICE_UNAVAILABLE`	Meta did not confirm the update / general update error.

Example error responses:

{ "errors": { "code": "WA_VAL_001", "group": "VALIDATION", "description": "Maximum 2 websites allowed." }, "isSuccess": false }

{ "errors": { "code": "META_033", "group": "VALIDATION", "description": "Failed to update business profile. Details: ..." }, "isSuccess": false }

{ "errors": { "code": "META_002", "group": "SERVICE_UNAVAILABLE", "description": "Failed to update business profile." }, "isSuccess": false }

The category value must be one of the Business Profile Category values (otherwise 422). Update is PATCH/partial; fields you do not send remain as they are on Meta. The profile picture is set through profilePictureReference (a single-use media handle), never as a URL — see the Changing the profile picture section above.

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Request Body

Changing the profile picture

Response

Examples

Errors

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Changing the profile picture

​Response

​Examples

​Errors

What it does

Endpoint

Headers

Path parameters

Request Body

Changing the profile picture

Response

Examples

Errors