API Reference / Endpoints

Update Subscriber

The Update Subscriber endpoint allows you to modify information for an existing subscriber. You can update their name, phone number, points, custom metadata fields, and tags.

Want the full picture in one fetch? The one-page integration guide covers every path with copy-paste code · OpenAPI spec · SDK: npm install waitlister

Endpoint Details

URL: https://waitlister.me/api/v1/waitlist/{waitlist-key}/subscribers/{id-or-email}
Method: PUT

Request

Headers

code

Content-Type: application/json
X-Api-Key: your-api-key

Path Parameters

Parameter	Description
`waitlist-key`	Your unique waitlist key, found in your waitlist settings
`id-or-email`	Either the subscriber's unique ID or their email address

Request Body

json

{
  "name": "Updated Name",
  "phone": "+1987654321",
  "points": 200,
  "metadata": {
    "company": "New Company",
    "status": "qualified"
  }
}

Optional Fields

Field	Type	Description
`name`	String	The subscriber's updated name
`phone`	String	The subscriber's updated phone number
`points`	Number	The subscriber's updated points value
`metadata`	Object	Additional fields to add or update in the subscriber's metadata
`add_tags`	Array of strings	Tags to add, by name (case-insensitive) or ID. A name the waitlist doesn't have yet is created as a new tag
`remove_tags`	Array of strings	Tags to remove, by name or ID. Tags the subscriber doesn't have are ignored
`tags`	Array of strings	Replace the subscriber's tags with exactly this set. `[]` removes all tags. Can't be combined with `add_tags` or `remove_tags`

Note: You only need to include the fields you want to update. Omitted fields will remain unchanged.

Response

Success Response `200`

json

{
  "success": true,
  "message": "Successfully updated subscriber",
  "data": {
    "subscriber": {
      "id": "xyzABC123",
      "email": "user@example.com",
      "name": "Updated Name",
      "phone": "+1987654321",
      "points": 200,
      "sign_up_token": "abc123xyz",
      "thank_you_url": "https://waitlister.me/thank-you/your-waitlist-key/abc123xyz",
      "updated_at": 1682345678901,
      "metadata": {
        "company": "New Company",
        "status": "qualified",
        "existing_field": "existing value"
      },
      "tags": [
        { "id": "tag_1760000000000", "name": "beta", "color": "blue" }
      ]
    }
  }
}

Response Fields

Field	Type	Description
`success`	Boolean	Always `true` for successful responses
`message`	String	A human-readable success message
`data.subscriber`	Object	The updated subscriber information
`data.subscriber.sign_up_token`	String	Unique token for this subscriber
`data.subscriber.thank_you_url`	String	URL to the subscriber's thank you page
`data.subscriber.updated_at`	Number	Timestamp of when the subscriber was updated
`data.subscriber.tags`	Array	The subscriber's tags after the update, each with `id`, `name`, and `color`

Error Responses

Not Found `404`

json

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Subscriber not found"
}

Bad Request `400`

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "At least one field to update must be provided"
}

Tag requests return a 400 when:

tags is combined with add_tags or remove_tags
a value isn't an array of non-empty strings, lists more than 20 tags, or has a name longer than 30 characters
an ID that looks like a tag ID (tag_…) doesn't exist on the waitlist
adding a new name would take the waitlist past 20 tags

The last two messages list the waitlist's existing tags. None of these errors change anything.

Examples