Free setup on annual plans

Sign up today!
Book a Demo

End Users

Home

> API Reference >

Endpoints >

End Users

API Reference: End Users endpoints

The End Users API manages the people represented in AnswerPal conversations: customers, leads, partners, employees or other contacts. The current endpoints support customer-scoped CRUD operations, UID-based lookup, ticket history for a person and linking extra unique identifiers.

Overview

End users are scoped to the authenticated customer from the JWT. Each end user can have profile fields and multiple UIDs such as email addresses, phone numbers, WhatsApp identifiers or external references. UID lookup also checks customerRef, so integrations can resolve a person by an external customer reference or by a stored UID.

Current endpoints

End-user records

  • GET /api/EndUsers – Bearer JWT
    Return a paginated customer-scoped list of end users. Query supports pageNumber, pageSize, sortBy, sortOrder and search.
  • POST /api/EndUsers – Bearer JWT
    Create an end user and optional UIDs. Customer scope is taken from the JWT; an empty customerType defaults to Lead.
  • GET /api/EndUsers/{id} – Bearer JWT
    Return one end user with its UIDs when it belongs to the authenticated customer.
  • PUT /api/EndUsers/{id} – Bearer JWT
    Update an end user and add, update or remove UIDs. An empty customerType keeps the existing value.
  • DELETE /api/EndUsers/{id} – Bearer JWT
    Delete one end user in the authenticated customer scope.

UID lookup and ticket history

  • GET /api/EndUsers/byUid – Bearer JWT
    Find end users by query parameter uid. The value is trimmed and matched against stored UIDs or customerRef in the authenticated customer.
  • GET /api/EndUsers/{id}/tickets – Bearer JWT
    Return paginated tickets connected to all UIDs on the end user, plus customerRef when present. Filters include status, customerRepID, channelType, channelIDs, uid, isClosed, isSpam, search, sortBy, sortOrder, pageNumber and pageSize.

UID assignment

  • POST /api/EndUserUIDs/assign – Bearer JWT
    Assign a UID to an existing end user in the same customer. uidType defaults to Email when empty. Duplicate links return 200 OK with a message; new links return 201 Created.

Auth, validation and errors

  • Authentication
    Protected AnswerPal API endpoints use JWT Bearer authentication. All End Users and EndUserUIDs endpoints require a bearer token.
  • Customer scope
    Every read, write and delete is limited to the authenticated customer’s ID. Records from another customer are treated as not found.
  • Validation
    customerType must be Lead, Customer, Partner or empty. Email UIDs must be syntactically valid e-mail addresses. Phone UIDs are normalized on create, update and assign.
  • Errors
    400 for invalid DTOs or invalid UID values, 401/403 for missing or rejected auth, 404 when the end user is not found in the customer scope and 201/204 on successful create/update/delete operations.

Fields and DTOs

EndUser fields

Profile fields

  • endUserID
    Response-only identifier on EndUserReadDTO.
  • firstname, lastname, name
    First and last name are request/response fields. name is a response-only convenience field combining them.
  • gender, otherContactDetails, aiDocumentation
    Optional profile and internal AI context fields.
  • customerRef
    Optional external reference, max 254 characters. UID lookup also checks this value.
  • customerType
    Optional classification. Allowed values: Lead, Customer or Partner. Empty defaults to Lead on create and keeps the existing value on update.

Localization and address fields

  • country, lang
    Optional country code and language code. country is stored as a 2-character value; lang as up to 5 characters.
  • street, houseNumber, postalCode, city, company
    Optional address and company fields.
  • uids
    List of UID objects returned on reads and accepted on create/update.

UID fields

Read and create UID fields

  • endUserUIDID
    Response-only identifier for a UID record.
  • uidType
    Type of identifier such as Email, Phone or WhatsApp. Max 20 characters on stored records.
  • uid
    Required identifier value. Email UIDs must be valid email addresses; stored UID values are trimmed.
  • isPrimary
    Marks the preferred UID for an end user.

Update and assign fields

  • endUserUIDID
    Optional in update payloads. Null creates a new UID unless an existing matching UID is found.
  • markAsDeleted
    Update-only flag. When true, the matching UID is removed instead of saved.
  • endUserID
    Required by POST /api/EndUserUIDs/assign to identify the existing end user.

Create and update payloads

Create and update payloads

  • EndUserCreateDTO
    Extends EndUserBaseDTO with uids: a list of { uidType, uid, isPrimary }.
  • EndUserUpdateDTO
    Extends EndUserBaseDTO with uids: a list of { endUserUIDID, uidType, uid, isPrimary, markAsDeleted }.
  • EndUserReadDTO
    Extends EndUserBaseDTO with endUserID, name and uids.
  • AssignUIDRequest
    Body for POST /api/EndUserUIDs/assign: { uid, endUserID, uidType, isPrimary }.

Query parameters

List query parameters

  • pageNumber, pageSize
    Pagination. Defaults are pageNumber 1 and pageSize 10.
  • sortBy, sortOrder
    Sorting fields passed through the shared ApplySort helper. sortOrder defaults to asc for EndUsers list.
  • search
    Searches end-user full-text data, UID values and customerRef prefix matches.

Ticket-history query parameters

  • status, customerRepID, channelType, channelIDs, uid
    Optional filters applied to the tickets matched from the route end user UID list and customerRef.
  • isClosed, isSpam, search
    Status and text filters for ticket history.
  • sortBy, sortOrder, pageNumber, pageSize
    Ticket-history sorting and pagination. Default sort is lastMessageDate descending when sortBy is omitted.

Ticket history response

Paginated response

  • items, totalCount, totalPages
    Both EndUsers list and end-user ticket history use the shared PaginatedResult shape.
  • TicketReadDTO
    Ticket history returns TicketReadDTO items, including ticket fields plus computed topics, aiFeedbackComments and lastEndUserMessageID.
  • lastEndUserMessageID
    Set only when exactly one end-user message is found for the returned ticket.
  • aiFeedbackComments
    Escalated feedback comments collected from ticket messages, newest first.

Examples

Create an end user

POST /api/EndUsers
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstname": "Jane",
  "lastname": "Doe",
  "customerRef": "ERP-3049353",
  "customerType": "Customer",
  "lang": "nl",
  "country": "BE",
  "uids": [
    {
      "uidType": "Email",
      "uid": "jane@example.com",
      "isPrimary": true
    }
  ]
}

Update a UID and remove another UID

PUT /api/EndUsers/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstname": "Jane",
  "customerType": "",
  "uids": [
    {
      "endUserUIDID": 12,
      "uidType": "Email",
      "uid": "jane.new@example.com",
      "isPrimary": true
    },
    {
      "endUserUIDID": 15,
      "uidType": "Phone",
      "uid": "+32470000000",
      "isPrimary": false,
      "markAsDeleted": true
    }
  ]
}

Assign a UID to an existing end user

POST /api/EndUserUIDs/assign
Authorization: Bearer <token>
Content-Type: application/json

{
  "uid": "visitor@example.com",
  "endUserID": 123,
  "uidType": "Email",
  "isPrimary": false
}

AssignUIDRequest

AssignUIDRequest fields

  • uid
    Required UID value. Email UIDs must be syntactically valid e-mail addresses.
  • endUserID
    Required existing end-user ID in the authenticated customer.
  • uidType
    Optional UID type. Empty values default to Email.
  • isPrimary
    Marks the assigned UID as primary.

Best practices and notes

  • Use stable external IDs in customerRef when your CRM or ERP already has a customer identifier.
  • Add all known identifiers to uids so email, phone, WhatsApp and chat conversations can be joined to the same person.
  • Set one primary UID per end user for UI display and default contact flows.
  • When updating customerType, send one of Lead, Customer or Partner. Send an empty value only when you intentionally want to preserve the existing value.
  • For ticket history, use the route ID as the end-user reference point. The endpoint derives the relevant UID list from that record.

FAQ

Yes. Use the uids list on create/update or POST /api/EndUserUIDs/assign to link extra email addresses, phone numbers, WhatsApp IDs or external identifiers.

The supplied uid query value is trimmed and matched against stored UID records and customerRef, scoped to the authenticated customer.

If the same UID is already linked to that end user, the API returns 200 OK with a message. A new link returns 201 Created with the UID record information.

Lead, Customer and Partner are accepted. Empty values default to Lead on create and keep the current value on update.

Contact Support

Contact Support

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons