Member Names

Send Zing the first and last name you hold for each member. Zing stores them with the member’s partner_user_id and shows them in the Partner Portal, so your team sees members under the names your systems use.

How member names work

• Separate from the app name. The names you send are stored separately. They never overwrite the name the member chose in the Zing app, and the app does not show them.
• Shown in the Partner Portal. The portal shows your names on member lists and profiles, and member search matches them.
• Returned by the Pull API. GET /users and GET /users/{partner_user_id} return first_name and last_name. Both are null until you set them.
• Cleared on removal. DELETE /users/{partner_user_id} clears both names.

Endpoints

Both endpoints use the same base URL, API key authentication, and rate limits as the Pull API. Send the body as JSON with Content-Type: application/json.

When to use each

• Batch — Use POST /users/names:batch for the initial backfill of existing members and for periodic syncs from your member system. Split larger sets into requests of up to 500 members.
• Single — Use PATCH /users/{partner_user_id}/name when one member’s name changes, for example right after a profile update in your system.

Update rules

Both endpoints apply the same rules to each member:

• Only the fields you send change. A field you omit keeps its current value.
• null or a blank string clears a field. For example, {"last_name": null} removes the last name and leaves the first name as it is.
• Values are trimmed. Leading and trailing whitespace is removed before the value is stored.
• At least one field is required. Send first_name, last_name, or both.

Each name must:

• Be a string or null.
• Be at most 150 characters after trimming.
• Not contain the NUL character (\u0000).

Unknown fields are rejected with 400. Only first_name and last_name are accepted in the single request body, plus partner_user_id in each batch item.

Set one member’s name

PATCH /users/{partner_user_id}/name

Request body

Responses

• 200 — Names stored. The response contains the member’s current first_name and last_name.
• 400 — Invalid body: no name fields, an unknown field, a value that is not a string, a name longer than 150 characters, or a NUL character.
• 404 — No member with this partner_user_id exists for your partner account, or the member was removed.

Example

curl -sS -X PATCH \
  -H "Authorization: Api-Key <API KEY>" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "last_name": "Doe"}' \
  "https://api.dev-ai.coach/v1/users/partner-usr-123/name"

Example response:

{
  "partner_user_id": "partner-usr-123",
  "first_name": "Jane",
  "last_name": "Doe"
}

To change only the first name, send only that field. The last name stays Doe:

{
  "first_name": "Janie"
}

Unknown member:

{
  "detail": "User not found."
}

Set names in a batch

POST /users/names:batch

Request body

Each item must include first_name, last_name, or both.

Validation is all or nothing

Zing validates the whole request before writing anything. If any item is invalid, or the same partner_user_id appears more than once, the request returns 400 and no names are changed. The detail message names the failing path, for example items.1.last_name.

Responses

• 200 — The request was valid. results has one entry per item, in request order:
  • updated — Names stored. first_name and last_name hold the member’s current names.
  • not_found — No member with this partner_user_id exists for your partner account, or the member was removed. Nothing is stored and both names are null.
• 400 — Invalid request: missing or empty items, more than 500 items, a duplicate partner_user_id, an item without name fields, an unknown field, or an invalid name.

A batch with not_found items still returns 200. Check status on each result.

Example

In this request, partner-usr-123 already has the last name Doe, and partner-usr-999 is not a member of this partner account.

curl -sS -X POST \
  -H "Authorization: Api-Key <API KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"partner_user_id": "partner-usr-456", "first_name": "Giulia", "last_name": "Bianchi"},
      {"partner_user_id": "partner-usr-123", "first_name": "Jane"},
      {"partner_user_id": "partner-usr-999", "last_name": null}
    ]
  }' \
  "https://api.dev-ai.coach/v1/users/names:batch"

Example response:

{
  "results": [
    {
      "partner_user_id": "partner-usr-456",
      "status": "updated",
      "first_name": "Giulia",
      "last_name": "Bianchi"
    },
    {
      "partner_user_id": "partner-usr-123",
      "status": "updated",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    {
      "partner_user_id": "partner-usr-999",
      "status": "not_found",
      "first_name": null,
      "last_name": null
    }
  ]
}

Example: rejected batch

The same partner_user_id appears twice, so the whole request is rejected and nothing is written:

{
  "items": [
    {"partner_user_id": "partner-usr-123", "first_name": "Jane"},
    {"partner_user_id": "partner-usr-123", "last_name": "Doe"}
  ]
}

Response (400):

{
  "detail": "items: Value error, Duplicate partner_user_id: partner-usr-123."
}

Fix the request and send it again. Combine the fields for one member into a single item.

Considerations

• Retries — Both endpoints are safe to retry. Sending the same names again stores the same values.
• not_found results — Zing has no member with that partner_user_id for your partner account. Check the ID against GET /users, and include the member again in your next periodic sync.
• Rate limits — If you receive 429, wait for the Retry-After seconds before retrying. Send batches one after another rather than in parallel.

For the full request and response schemas, see the Reference (opens in new window).