# PATCH /v1/influencers/:influencerId (/docs/api/reference/influencers/patch-influencer)



<Endpoint method="PATCH" path="/v1/influencers/:influencerId" scope="influencers:write" phase="1" />

Patch identity fields you want to change. Everything omitted is left alone. The body is strict — unknown fields are rejected. Returns the full updated record.

## Path parameters [#path-parameters]

<Parameters
  rows="[
  { name: 'influencerId', type: 'string (uuid)', required: true, description: 'The influencer id.' },
]"
/>

## Body [#body]

<Parameters
  title="Body (all optional, at least one)"
  rows="[
  { name: 'name', type: 'string', description: 'Display name (1-128).' },
  { name: 'gender', type: 'string | null', description: 'Pass null to clear.', enum: ['male', 'female', 'nonbinary', 'unspecified'] },
  { name: 'ageRange', type: 'string | null', description: 'Pass null to clear.' },
  { name: 'ethnicity', type: 'string | null', description: '' },
  { name: 'bodyType', type: 'string | null', description: '' },
  { name: 'hairColor', type: 'string | null', description: '' },
  { name: 'hairStyle', type: 'string | null', description: '' },
  { name: 'style', type: 'string | null', description: '' },
  { name: 'vibe', type: 'string | null', description: '' },
  { name: 'voiceDescription', type: 'string | null', description: '' },
  { name: 'personality', type: 'object', description: 'Nested partial. Merges with existing traits — pass only the keys you want to change.' },
]"
/>

Reference images aren't patched here; use [`POST /v1/influencers/:influencerId/reference-images`](/docs/api/reference/influencers/reference-images).

## Request [#request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```sh title="terminal"
    curl -X PATCH https://api.layers.com/v1/influencers/{influencerId} \
      -H "X-Api-Key: $LAYERS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "vibe": "precise and energetic", "personality": { "humor": "observational" } }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="patch-influencer.ts"
    const res = await fetch(
      `https://api.layers.com/v1/influencers/${influencerId}`,
      {
        method: 'PATCH',
        headers: {
          'X-Api-Key': process.env.LAYERS_API_KEY!,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ vibe: 'precise and energetic' }),
      },
    );
    const influencer = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```py title="patch_influencer.py"
    import os, httpx

    r = httpx.patch(
        f"https://api.layers.com/v1/influencers/{influencer_id}",
        headers={
            "X-Api-Key": os.environ["LAYERS_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"vibe": "precise and energetic"},
    )
    influencer = r.json()
    ```
  </Tab>
</Tabs>

## Responses [#responses]

<Response status="200" description="Full updated influencer row (same shape as GET).">
  ```json
  {
    "influencerId": "inf_01HXZ9...",
    "projectId": "proj_01HX...",
    "name": "Ava Chen",
    "gender": "female",
    "ageRange": "25-34",
    "vibe": "precise and energetic",
    "personality": {
      "traits": ["curious", "warm", "direct"],
      "humor": "observational"
    },
    "referenceImages": [],
    "status": "ready",
    "createdAt": "2026-04-01T14:22:10Z",
    "updatedAt": "2026-04-18T09:18:44Z"
  }
  ```
</Response>

<Response status="422" description="Validation failed — bad enum, unknown field, or wrong type.">
  ```json
  {
    "error": {
      "code": "VALIDATION",
      "message": "Invalid body.",
      "requestId": "req_...",
      "details": { "fieldErrors": { "gender": ["Invalid enum value"] } }
    }
  }
  ```
</Response>

<Response status="404" description="Influencer not in this org, or deleted.">
  ```json
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Influencer not found.",
      "requestId": "req_..."
    }
  }
  ```
</Response>

## Notes [#notes]

* **Personality is merged, not replaced.** The server reads existing `personality` JSON and shallow-merges your patch. To clear a key, set it to `null` explicitly.
* **Attributes outside the schema are dropped.** Unknown fields produce a `VALIDATION` response.

## Errors [#errors]

| Code              | When                                        |
| ----------------- | ------------------------------------------- |
| `VALIDATION`      | Bad type, unknown field, enum out of range. |
| `NOT_FOUND`       | Influencer not in this org.                 |
| `FORBIDDEN_SCOPE` | Key lacks `influencers:write`.              |

## See also [#see-also]

* [Read one influencer](/docs/api/reference/influencers/get-influencer)
* [Bind reference images](/docs/api/reference/influencers/reference-images)
* [Delete an influencer](/docs/api/reference/influencers/delete-influencer)